Commits

Georg Brandl committed 1ce281d

Add node docstrings, remove duplication of class names.

Comments (0)

Files changed (1)

 
 from docutils import nodes
 
-# index markup
-class index(nodes.Invisible, nodes.Inline, nodes.TextElement): pass
+
+class toctree(nodes.General, nodes.Element):
+    """Node for inserting a "TOC tree"."""
+
 
 # domain-specific object descriptions (class, function etc.)
 
-# parent node for signature and content
-class desc(nodes.Admonition, nodes.Element): pass
+class desc(nodes.Admonition, nodes.Element):
+    """Node for object descriptions.
 
-# additional name parts (module name, class name)
-class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement): pass
+    This node is similar to a "definition list" with one definition.  It
+    contains one or more ``desc_signature`` and a ``desc_content``.
+    """
+
+class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for object signatures.
+
+    The "term" part of the custom Sphinx definition list.
+    """
+
+
+# nodes to use within a desc_signature
+
+class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for additional name parts (module name, class name)."""
 # compatibility alias
 desc_classname = desc_addname
-# return type (C); object type
-class desc_type(nodes.Part, nodes.Inline, nodes.TextElement): pass
-# -> annotation (Python)
+
+class desc_type(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for return types or object type names."""
+
 class desc_returns(desc_type):
+    """Node for a "returns" annotation (a la -> in Python)."""
     def astext(self):
         return ' -> ' + nodes.TextElement.astext(self)
-# main name of object
-class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass
-# argument list
-class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement): pass
+
+class desc_name(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for the main object name."""
+
 class desc_parameterlist(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for a general parameter list."""
     child_text_separator = ', '
-class desc_parameter(nodes.Part, nodes.Inline, nodes.TextElement): pass
+
+class desc_parameter(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for a single parameter."""
+
 class desc_optional(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for marking optional parts of the parameter list."""
     child_text_separator = ', '
     def astext(self):
         return '[' + nodes.TextElement.astext(self) + ']'
-# annotation (not Python 3-style annotations)
-class desc_annotation(nodes.Part, nodes.Inline, nodes.TextElement): pass
 
-# node for content
-class desc_content(nodes.General, nodes.Element): pass
+class desc_annotation(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for signature annotations (not Python 3-style annotations)."""
 
-# \versionadded, \versionchanged, \deprecated
-class versionmodified(nodes.Admonition, nodes.TextElement): pass
+class desc_content(nodes.General, nodes.Element):
+    """Node for object description content.
 
-# seealso
-class seealso(nodes.Admonition, nodes.Element): pass
+    This is the "definition" part of the custom Sphinx definition list.
+    """
 
-# productionlist
-class productionlist(nodes.Admonition, nodes.Element): pass
-class production(nodes.Part, nodes.Inline, nodes.TextElement): pass
 
-# toc tree
-class toctree(nodes.General, nodes.Element): pass
+# new admonition-like constructs
 
-# centered
-class centered(nodes.Part, nodes.Element): pass
+class versionmodified(nodes.Admonition, nodes.TextElement):
+    """Node for version change entries.
 
-# pending xref
-class pending_xref(nodes.Inline, nodes.Element): pass
+    Currently used for "versionadded", "versionchanged" and "deprecated"
+    directives.
+    """
 
-# compact paragraph -- never makes a <p>
-class compact_paragraph(nodes.paragraph): pass
+class seealso(nodes.Admonition, nodes.Element):
+    """Custom "see also" admonition."""
 
-# reference to a file to download
-class download_reference(nodes.reference): pass
+class productionlist(nodes.Admonition, nodes.Element):
+    """Node for grammar production lists.
 
-# for the ACKS list
-class acks(nodes.Element): pass
+    Contains ``production`` nodes.
+    """
 
-# for horizontal lists
-class hlist(nodes.Element): pass
-class hlistcol(nodes.Element): pass
+class production(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for a single grammar production rule."""
 
-# sets the highlighting language for literal blocks
-class highlightlang(nodes.Element): pass
 
-# like emphasis, but doesn't apply further text processors, e.g. smartypants
-class literal_emphasis(nodes.emphasis): pass
+# other directive-level nodes
 
-# for abbreviations (with explanations)
-class abbreviation(nodes.Inline, nodes.TextElement): pass
+class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
+    """Node for index entries.
 
-# glossary
-class glossary(nodes.Element): pass
+    This node is created by the ``index`` directive and has one attribute,
+    ``entries``.  Its value is a list of 4-tuples of ``(entrytype, entryname,
+    target, ignored)``.
 
-# start of a file, used in the LaTeX builder only
-class start_of_file(nodes.Element): pass
+    *entrytype* is one of "single", "pair", "double", "triple".
+    """
 
-# tabular column specification, used for the LaTeX writer
-class tabular_col_spec(nodes.Element): pass
+class centered(nodes.Part, nodes.Element):
+    """Deprecated."""
 
-# only (in/exclusion based on tags)
-class only(nodes.Element): pass
+class acks(nodes.Element):
+    """Special node for "acks" lists."""
 
-# meta directive -- same as docutils' standard meta node, but pickleable
-class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass
+class hlist(nodes.Element):
+    """Node for "horizontal lists", i.e. lists that should be compressed to
+    take up less vertical space.
+    """
 
-# make them known to docutils. this is needed, because the HTML writer
-# will choke at some point if these are not added
-nodes._add_node_class_names("""index desc desc_content desc_signature
-      desc_type desc_returns desc_addname desc_name desc_parameterlist
-      desc_parameter desc_optional download_reference hlist hlistcol
-      centered versionmodified seealso productionlist production toctree
-      pending_xref compact_paragraph highlightlang literal_emphasis
-      abbreviation glossary acks module start_of_file tabular_col_spec
-      meta""".split())
+class hlistcol(nodes.Element):
+    """Node for one column in a horizontal list."""
+
+class compact_paragraph(nodes.paragraph):
+    """Node for a compact paragraph (which never makes a <p> node)."""
+
+class glossary(nodes.Element):
+    """Node to insert a glossary."""
+
+class only(nodes.Element):
+    """Node for "only" directives (conditional inclusion based on tags)."""
+
+
+# meta-information nodes
+
+class start_of_file(nodes.Element):
+    """Node to mark start of a new file, used in the LaTeX builder only."""
+
+class highlightlang(nodes.Element):
+    """Inserted to set the highlight language and line number options for
+    subsequent code blocks.
+    """
+
+class tabular_col_spec(nodes.Element):
+    """Node for specifying tabular columns, used for LaTeX output."""
+
+class meta(nodes.Special, nodes.PreBibliographic, nodes.Element):
+    """Node for meta directive -- same as docutils' standard meta node,
+    but pickleable.
+    """
+
+
+# inline nodes
+
+class pending_xref(nodes.Inline, nodes.Element):
+    """Node for cross-references that cannot be resolved without complete
+    information about all documents.
+
+    These nodes are resolved before writing output, in
+    BuildEnvironment.resolve_references.
+    """
+
+class download_reference(nodes.reference):
+    """Node for download references, similar to pending_xref."""
+
+class literal_emphasis(nodes.emphasis):
+    """Node that behaves like `emphasis`, but further text processors are not
+    applied (e.g. smartypants for HTML output).
+    """
+
+class abbreviation(nodes.Inline, nodes.TextElement):
+    """Node for abbreviations with explanations."""
+
+
+# make the new nodes known to docutils; needed because the HTML writer will
+# choke at some point if these are not added
+nodes._add_node_class_names(k for k in globals().keys()
+                            if k != 'nodes' and k[0] != '_')