Docstring harmonization.

sphinx/__init__.py

@@ -37,6 +37,7 @@ if '+' in __version__ or 'pre' in __version__:
 
 
 def main(argv=sys.argv):
+    """Sphinx build "main" command-line entry."""
     if sys.version_info[:3] < (2, 4, 0):
         sys.stderr.write('Error: Sphinx requires at least '
                          'Python 2.4 to run.\n')

sphinx/application.py

@@ -133,9 +133,8 @@ class Sphinx(object):
         self._init_builder(buildername)
 
     def _init_i18n(self):
-        """
+        """Load translated strings from the configured localedirs if enabled in
-        Load translated strings from the configured localedirs if
+        the configuration.
-        enabled in the configuration.
         """
         if self.config.language is not None:
             self.info(bold('loading translations [%s]... ' %
@@ -484,8 +483,7 @@ class TemplateBridge(object):
     """
 
     def init(self, builder, theme=None, dirs=None):
-        """
+        """Called by the builder to initialize the template system.
-        Called by the builder to initialize the template system.
 
         *builder* is the builder object; you'll probably want to look at the
         value of ``builder.config.templates_path``.
@@ -496,23 +494,20 @@ class TemplateBridge(object):
         raise NotImplementedError('must be implemented in subclasses')
 
     def newest_template_mtime(self):
-        """
+        """Called by the builder to determine if output files are outdated
-        Called by the builder to determine if output files are outdated
         because of template changes.  Return the mtime of the newest template
         file that was changed.  The default implementation returns ``0``.
         """
         return 0
 
     def render(self, template, context):
-        """
+        """Called by the builder to render a template given as a filename with
-        Called by the builder to render a template given as a filename with a
+        a specified context (a Python dictionary).
-        specified context (a Python dictionary).
         """
         raise NotImplementedError('must be implemented in subclasses')
 
     def render_string(self, template, context):
-        """
+        """Called by the builder to render a template given as a string with a
-        Called by the builder to render a template given as a string with a
         specified context (a Python dictionary).
         """
         raise NotImplementedError('must be implemented in subclasses')

sphinx/builders/__init__.py

@@ -55,16 +55,13 @@ class Builder(object):
 
     # helper methods
     def init(self):
-        """
+        """Load necessary templates and perform initialization.  The default
-        Load necessary templates and perform initialization.  The default
         implementation does nothing.
         """
         pass
 
     def create_template_bridge(self):
-        """
+        """Return the template bridge configured."""
-        Return the template bridge configured.
-        """
         if self.config.template_bridge:
             self.templates = self.app.import_object(
                 self.config.template_bridge, 'template_bridge setting')()
@@ -73,23 +70,23 @@ class Builder(object):
             self.templates = BuiltinTemplateLoader()
 
     def get_target_uri(self, docname, typ=None):
-        """
+        """Return the target URI for a document name.
-        Return the target URI for a document name (*typ* can be used to qualify
+
-        the link characteristic for individual builders).
+        *typ* can be used to qualify the link characteristic for individual
+        builders.
         """
         raise NotImplementedError
 
     def get_relative_uri(self, from_, to, typ=None):
-        """
+        """Return a relative URI between two source filenames.
-        Return a relative URI between two source filenames. May raise
+
-        environment.NoUri if there's no way to return a sensible URI.
+        May raise environment.NoUri if there's no way to return a sensible URI.
         """
         return relative_uri(self.get_target_uri(from_),
                             self.get_target_uri(to, typ))
 
     def get_outdated_docs(self):
-        """
+        """Return an iterable of output files that are outdated, or a string
-        Return an iterable of output files that are outdated, or a string
         describing what an update build will build.
 
         If the builder does not output individual files corresponding to
@@ -129,9 +126,7 @@ class Builder(object):
     supported_image_types = []
 
     def post_process_images(self, doctree):
-        """
+        """Pick the best candidate for all image URIs."""
-        Pick the best candidate for all image URIs.
-        """
         for node in doctree.traverse(nodes.image):
             if '?' in node['candidates']:
                 # don't rewrite nonlocal image URIs
@@ -198,9 +193,9 @@ class Builder(object):
                        'out of date' % len(to_build))
 
     def build(self, docnames, summary=None, method='update'):
-        """
+        """Main build method.
-        Main build method.  First updates the environment, and then
+
-        calls :meth:`write`.
+        First updates the environment, and then calls :meth:`write`.
         """
         if summary:
             self.info(bold('building [%s]: ' % self.name), nonl=1)
@@ -302,14 +297,16 @@ class Builder(object):
         raise NotImplementedError
 
     def finish(self):
-        """
+        """Finish the building process.
-        Finish the building process.  The default implementation does nothing.
+
+        The default implementation does nothing.
         """
         pass
 
     def cleanup(self):
-        """
+        """Cleanup any resources.
-        Cleanup any resources.  The default implementation does nothing.
+
+        The default implementation does nothing.
         """
         pass
 

sphinx/builders/devhelp.py

@@ -42,7 +42,6 @@ except ImportError:
 class DevhelpBuilder(StandaloneHTMLBuilder):
     """
     Builder that also outputs GNOME Devhelp file.
-
     """
     name = 'devhelp'
 

sphinx/builders/epub.py

@@ -130,7 +130,8 @@ _refuri_re = re.compile("([^#:]*#)(.*)")
 # The epub publisher
 
 class EpubBuilder(StandaloneHTMLBuilder):
-    """Builder that outputs epub files.
+    """
+    Builder that outputs epub files.
 
     It creates the metainfo files container.opf, toc.ncx, mimetype, and
     META-INF/container.xml.  Afterwards, all necessary files are zipped to an
@@ -222,12 +223,12 @@ class EpubBuilder(StandaloneHTMLBuilder):
             })
 
     def fix_fragment(self, match):
-        """Return a href attribute with colons replaced by hyphens.
+        """Return a href attribute with colons replaced by hyphens."""
-        """
         return match.group(1) + match.group(2).replace(':', '-')
 
     def fix_ids(self, tree):
         """Replace colons with hyphens in href and id attributes.
+
         Some readers crash because they interpret the part as a
         transport protocol specification.
         """
@@ -246,8 +247,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
             node.attributes['ids'] = newids
 
     def add_visible_links(self, tree):
-        """Append visible link targets after external links.
+        """Append visible link targets after external links."""
-        """
         for node in tree.traverse(nodes.reference):
             uri = node.get('refuri', '')
             if (uri.startswith('http:') or uri.startswith('https:') or
@@ -261,6 +261,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
     def write_doc(self, docname, doctree):
         """Write one document file.
+
         This method is overwritten in order to fix fragment identifiers
         and to add visible external links.
         """
@@ -269,8 +270,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         return StandaloneHTMLBuilder.write_doc(self, docname, doctree)
 
     def fix_genindex(self, tree):
-        """Fix href attributes for genindex pages.
+        """Fix href attributes for genindex pages."""
-        """
         # XXX: modifies tree inline
         # Logic modeled from themes/basic/genindex.html
         for key, columns in tree:
@@ -288,8 +288,9 @@ class EpubBuilder(StandaloneHTMLBuilder):
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
         """Create a rendered page.
-        This method is overwritten for genindex pages in order to fix
+
-        href link attributes.
+        This method is overwritten for genindex pages in order to fix href link
+        attributes.
         """
         if pagename.startswith('genindex'):
             self.fix_genindex(addctx['genindexentries'])
@@ -413,6 +414,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
     def insert_subnav(self, node, subnav):
         """Insert nested navpoints for given node.
+
         The node and subnav are already rendered to text.
         """
         nlist = node.rsplit('\n', 1)
@@ -422,8 +424,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
     def build_navpoints(self, nodes):
         """Create the toc navigation structure.
 
-        Subelements of a node are nested inside the navpoint.
+        Subelements of a node are nested inside the navpoint.  For nested nodes
-        For nested nodes the parent node is reinserted in the subnav.
+        the parent node is reinserted in the subnav.
         """
         navstack = []
         navlist = []
@@ -461,8 +463,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
         return '\n'.join(navlist)
 
     def toc_metadata(self, level, navpoints):
-        """Create a dictionary with all metadata for the toc.ncx
+        """Create a dictionary with all metadata for the toc.ncx file
-        file properly escaped.
+        properly escaped.
         """
         metadata = {}
         metadata['uid'] = self.config.epub_uid
@@ -487,8 +489,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
     def build_epub(self, outdir, outname):
         """Write the epub file.
 
-        It is a zip file with the mimetype file stored uncompressed
+        It is a zip file with the mimetype file stored uncompressed as the first
-        as the first entry.
+        entry.
         """
         self.info('writing %s file...' % outname)
         projectfiles = ['META-INF/container.xml', 'content.opf', 'toc.ncx'] \

sphinx/builders/html.py

@@ -587,8 +587,7 @@ class StandaloneHTMLBuilder(Builder):
             self.theme.cleanup()
 
     def post_process_images(self, doctree):
-        """
+        """Pick the best candidate for an image and link down-scaled images to
-        Pick the best candidate for an image and link down-scaled images to
         their high res version.
         """
         Builder.post_process_images(self, doctree)

sphinx/config.py

@@ -25,7 +25,9 @@ if sys.version_info >= (3, 0):
     CONFIG_SYNTAX_ERROR += "\nDid you change the syntax from 2.x to 3.x?"
 
 class Config(object):
-    """Configuration file abstraction."""
+    """
+    Configuration file abstraction.
+    """
 
     # the values are: (default, what needs to be rebuilt if changed)
 

sphinx/domains/__init__.py

@@ -66,9 +66,8 @@ class Index(object):
         self.domain = domain
 
     def generate(self, docnames=None):
-        """
+        """Return entries for the index given by *name*.  If *docnames* is
-        Return entries for the index given by *name*.  If *docnames* is given,
+        given, restrict to entries referring to these docnames.
-        restrict to entries referring to these docnames.
 
         The return value is a tuple of ``(content, collapse)``, where *collapse*
         is a boolean that determines if sub-entries should start collapsed (for
@@ -158,8 +157,7 @@ class Domain(object):
         self.objtypes_for_role = self._role2type.get
 
     def role(self, name):
-        """
+        """Return a role adapter function that always gives the registered
-        Return a role adapter function that always gives the registered
         role its full name ('domain:name') as the first argument.
         """
         if name in self._role_cache:
@@ -175,8 +173,7 @@ class Domain(object):
         return role_adapter
 
     def directive(self, name):
-        """
+        """Return a directive adapter class that always gives the registered
-        Return a directive adapter class that always gives the registered
         directive its full name ('domain:name') as ``self.name``.
         """
         if name in self._directive_cache:
@@ -195,21 +192,16 @@ class Domain(object):
     # methods that should be overwritten
 
     def clear_doc(self, docname):
-        """
+        """Remove traces of a document in the domain-specific inventories."""
-        Remove traces of a document in the domain-specific inventories.
-        """
         pass
 
     def process_doc(self, env, docname, document):
-        """
+        """Process a document after it is read by the environment."""
-        Process a document after it is read by the environment.
-        """
         pass
 
     def resolve_xref(self, env, fromdocname, builder,
                      typ, target, node, contnode):
-        """
+        """Resolve the pending_xref *node* with the given *typ* and *target*.
-        Resolve the ``pending_xref`` *node* with the given *typ* and *target*.
 
         This method should return a new node, to replace the xref node,
         containing the *contnode* which is the markup content of the
@@ -225,8 +217,7 @@ class Domain(object):
         pass
 
     def get_objects(self):
-        """
+        """Return an iterable of "object descriptions", which are tuples with
-        Return an iterable of "object descriptions", which are tuples with
         five items:
 
         * `name`     -- fully qualified name
@@ -245,9 +236,7 @@ class Domain(object):
         return []
 
     def get_type_name(self, type, primary=False):
-        """
+        """Return full name for given ObjType."""
-        Return full name for given ObjType.
-        """
         if primary:
             return type.lname
         return _('%s %s') % (self.label, type.lname)

sphinx/domains/cpp.py

@@ -135,29 +135,31 @@ class DefExpr(object):
     __hash__ = None
 
     def clone(self):
-        """Close a definition expression node"""
+        """Clone a definition expression node."""
         return deepcopy(self)
 
     def get_id(self):
-        """Returns the id for the node"""
+        """Return the id for the node."""
         return u''
 
     def get_name(self):
-        """Returns the name.  Returns either `None` or a node with
+        """Return the name.
-        a name you might call :meth:`split_owner` on.
+
+        Returns either `None` or a node with a name you might call
+        :meth:`split_owner` on.
         """
         return None
 
     def split_owner(self):
-        """Nodes returned by :meth:`get_name` can split off their
+        """Nodes returned by :meth:`get_name` can split off their owning parent.
-        owning parent.  This function returns the owner and the
+
-        name as a tuple of two items.  If a node does not support
+        This function returns the owner and the name as a tuple of two items.
-        it, :exc:`NotImplementedError` is raised.
+        If a node does not support it, :exc:`NotImplementedError` is raised.
         """
         raise NotImplementedError()
 
     def prefix(self, prefix):
-        """Prefixes a name node (a node returned by :meth:`get_name`)."""
+        """Prefix a name node (a node returned by :meth:`get_name`)."""
         raise NotImplementedError()
 
     def __str__(self):
@@ -984,8 +986,9 @@ class CPPFunctionObject(CPPObject):
 
 
 class CPPCurrentNamespace(Directive):
-    """This directive is just to tell Sphinx that we're documenting
+    """
-    stuff in namespace foo.
+    This directive is just to tell Sphinx that we're documenting stuff in
+    namespace foo.
     """
 
     has_content = False

sphinx/domains/javascript.py

@@ -148,7 +148,7 @@ class JSCallable(JSObject):
 
 
 class JSConstructor(JSCallable):
-    """Like a callable but with a different prefix"""
+    """Like a callable but with a different prefix."""
     display_prefix = 'class '
 
 

sphinx/domains/python.py

@@ -63,22 +63,21 @@ class PyObject(ObjectDescription):
     ]
 
     def get_signature_prefix(self, sig):
-        """
+        """May return a prefix to put before the object name in the
-        May return a prefix to put before the object name in the signature.
+        signature.
         """
         return ''
 
     def needs_arglist(self):
-        """
+        """May return true if an empty argument list is to be generated even if
-        May return true if an empty argument list is to be generated even if
         the document contains none.
         """
         return False
 
     def handle_signature(self, sig, signode):
-        """
+        """Transform a Python signature into RST nodes.
-        Transform a Python signature into RST nodes.
+
-        Returns (fully qualified name of the thing, classname if any).
+        Return (fully qualified name of the thing, classname if any).
 
         If inside a class, the current class name is handled intelligently:
         * it is stripped from the displayed name if present
@@ -167,9 +166,7 @@ class PyObject(ObjectDescription):
         return fullname, name_prefix
 
     def get_index_text(self, modname, name):
-        """
+        """Return the text for the index entry of the object."""
-        Return the text for the index entry of the object.
-        """
         raise NotImplementedError('must be implemented in subclasses')
 
     def add_target_and_index(self, name_cls, sig, signode):
@@ -548,9 +545,8 @@ class PythonDomain(Domain):
                 del self.data['modules'][modname]
 
     def find_obj(self, env, modname, classname, name, type, searchmode=0):
-        """
+        """Find a Python object for "name", perhaps using the given module
-        Find a Python object for "name", perhaps using the given module and/or
+        and/or classname.  Returns a list of (name, object entry) tuples.
-        classname.  Returns a list of (name, object entry) tuples.
         """
         # skip parens
         if name[-2:] == '()':

sphinx/domains/rst.py

@@ -59,9 +59,10 @@ class ReSTMarkup(ObjectDescription):
 
 
 def parse_directive(d):
-    """
+    """Parse a directive signature.
-    Parses a directive signature. Returns (directive, arguments) string tuple.
+
-    if no arguments are given, returns (directive, '').
+    Returns (directive, arguments) string tuple.  If no arguments are given,
+    returns (directive, '').
     """
     dir = d.strip()
     if not dir.startswith('.'):

sphinx/environment.py

@@ -417,12 +417,12 @@ class BuildEnvironment:
             domain.clear_doc(docname)
 
     def doc2path(self, docname, base=True, suffix=None):
-        """
+        """Return the filename for the document name.
-        Return the filename for the document name.
+
-        If base is True, return absolute path under self.srcdir.
+        If *base* is True, return absolute path under self.srcdir.
-        If base is None, return relative path to self.srcdir.
+        If *base* is None, return relative path to self.srcdir.
-        If base is a path string, return absolute path under that.
+        If *base* is a path string, return absolute path under that.
-        If suffix is not None, add it instead of config.source_suffix.
+        If *suffix* is not None, add it instead of config.source_suffix.
         """
         docname = docname.replace(SEP, path.sep)
         suffix = suffix or self.config.source_suffix
@@ -434,8 +434,8 @@ class BuildEnvironment:
             return path.join(base, docname) + suffix
 
     def find_files(self, config):
-        """
+        """Find all source files in the source dir and put them in
-        Find all source files in the source dir and put them in self.found_docs.
+        self.found_docs.
         """
         matchers = compile_matchers(
             config.exclude_patterns[:] +
@@ -448,9 +448,7 @@ class BuildEnvironment:
             self.srcdir, config.source_suffix, exclude_matchers=matchers))
 
     def get_outdated_files(self, config_changed):
-        """
+        """Return (added, changed, removed) sets."""
-        Return (added, changed, removed) sets.
-        """
         # clear all files no longer present
         removed = set(self.all_docs) - self.found_docs
 
@@ -496,12 +494,12 @@ class BuildEnvironment:
         return added, changed, removed
 
     def update(self, config, srcdir, doctreedir, app=None):
-        """
+        """(Re-)read all files new or changed since last update.
-        (Re-)read all files new or changed since last update.  Returns a
+
-        summary, the total count of documents to reread and an iterator that
+        Returns a summary, the total count of documents to reread and an
-        yields docnames as it processes them.  Store all environment docnames in
+        iterator that yields docnames as it processes them.  Store all
-        the canonical format (ie using SEP as a separator in place of
+        environment docnames in the canonical format (ie using SEP as a
-        os.path.sep).
+        separator in place of os.path.sep).
         """
         config_changed = False
         if self.config is None:
@@ -632,8 +630,8 @@ class BuildEnvironment:
         roles.role = role
 
     def read_doc(self, docname, src_path=None, save_parsed=True, app=None):
-        """
+        """Parse a file and add/update inventory entries for the doctree.
-        Parse a file and add/update inventory entries for the doctree.
+
         If srcpath is given, read from a different source file.
         """
         # remove all inventory entries for that file
@@ -785,9 +783,7 @@ class BuildEnvironment:
     # post-processing of read doctrees
 
     def filter_messages(self, doctree):
-        """
+        """Filter system messages from a doctree."""
-        Filter system messages from a doctree.
-        """
         filterlevel = self.config.keep_warnings and 2 or 5
         for node in doctree.traverse(nodes.system_message):
             if node['level'] < filterlevel:
@@ -795,9 +791,7 @@ class BuildEnvironment:
 
 
     def process_dependencies(self, docname, doctree):
-        """
+        """Process docutils-generated dependency info."""
-        Process docutils-generated dependency info.
-        """
         cwd = os.getcwd()
         frompath = path.join(path.normpath(self.srcdir), 'dummy')
         deps = doctree.settings.record_dependencies
@@ -811,9 +805,7 @@ class BuildEnvironment:
             self.dependencies.setdefault(docname, set()).add(relpath)
 
     def process_downloads(self, docname, doctree):
-        """
+        """Process downloadable file paths. """
-        Process downloadable file paths.
-        """
         docdir = path.dirname(self.doc2path(docname, base=None))
         for node in doctree.traverse(addnodes.download_reference):
             targetname = node['reftarget']
@@ -831,9 +823,7 @@ class BuildEnvironment:
             node['filename'] = uniquename
 
     def process_images(self, docname, doctree):
-        """
+        """Process and rewrite image URIs."""
-        Process and rewrite image URIs.
-        """
         docdir = path.dirname(self.doc2path(docname, base=None))
         for node in doctree.traverse(nodes.image):
             # Map the mimetype to the corresponding image.  The writer may
@@ -888,8 +878,8 @@ class BuildEnvironment:
                 self.images.add_file(docname, imgpath)
 
     def process_metadata(self, docname, doctree):
-        """
+        """Process the docinfo part of the doctree as metadata.
-        Process the docinfo part of the doctree as metadata.
+
         Keep processing minimal -- just return what docutils says.
         """
         self.metadata[docname] = md = {}
@@ -974,8 +964,7 @@ class BuildEnvironment:
                     item.replace(para, compact_para)
 
     def create_title_from(self, docname, document):
-        """
+        """Add a title node to the document (just copy the first section title),
-        Add a title node to the document (just copy the first section title),
         and store that title in the environment.
         """
         titlenode = nodes.title()
@@ -1013,7 +1002,8 @@ class BuildEnvironment:
 
     def note_toctree(self, docname, toctreenode):
         """Note a TOC tree directive in a document and gather information about
-           file relations from it."""
+        file relations from it.
+        """
         if toctreenode['glob']:
             self.glob_toctrees.add(docname)
         if toctreenode.get('numbered'):
@@ -1119,7 +1109,9 @@ class BuildEnvironment:
 
     def get_domain(self, domainname):
         """Return the domain instance with the specified name.
-        Raises an ExtensionError if the domain is not registered."""
+
+        Raises an ExtensionError if the domain is not registered.
+        """
         try:
             return self.domains[domainname]
         except KeyError:
@@ -1144,7 +1136,8 @@ class BuildEnvironment:
     def get_and_resolve_doctree(self, docname, builder, doctree=None,
                                 prune_toctrees=True):
         """Read the doctree from the pickle, resolve cross-references and
-           toctrees and return it."""
+        toctrees and return it.
+        """
         if doctree is None:
             doctree = self.get_doctree(docname)
 
@@ -1164,8 +1157,7 @@ class BuildEnvironment:
 
     def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0,
                         titles_only=False, collapse=False, includehidden=False):
-        """
+        """Resolve a *toctree* node into individual bullet lists with titles
-        Resolve a *toctree* node into individual bullet lists with titles
         as items, returning None (if no containing titles are found) or
         a new node.
 
@@ -1593,7 +1585,6 @@ class BuildEnvironment:
 
     def check_consistency(self):
         """Do consistency checks."""
-
         for docname in sorted(self.all_docs):
             if docname not in self.files_to_rebuild:
                 if docname == self.config.master_doc:

sphinx/ext/autodoc.py

@@ -85,7 +85,8 @@ def members_set_option(arg):
 
 def bool_option(arg):
     """Used to convert flag options to auto directives.  (Instead of
-    directives.flag(), which returns None.)"""
+    directives.flag(), which returns None).
+    """
     return True
 
 
@@ -133,8 +134,7 @@ class AutodocReporter(object):
 # Some useful event listener factories for autodoc-process-docstring.
 
 def cut_lines(pre, post=0, what=None):
-    """
+    """Return a listener that removes the first *pre* and last *post*
-    Return a listener that removes the first *pre* and last *post*
     lines of every docstring.  If *what* is a sequence of strings,
     only docstrings of a type in *what* will be processed.
 
@@ -160,9 +160,8 @@ def cut_lines(pre, post=0, what=None):
     return process
 
 def between(marker, what=None, keepempty=False, exclude=False):
-    """
+    """Return a listener that either keeps, or if *exclude* is True excludes,
-    Return a listener that either keeps, or if *exclude* is True excludes, lines
+    lines between lines that match the *marker* regular expression.  If no line
-    between lines that match the *marker* regular expression.  If no line
     matches, the resulting docstring would be empty, so no change will be made
     unless *keepempty* is true.
 
@@ -262,8 +261,7 @@ class Documenter(object):
         self.directive.result.append(self.indent + line, source, *lineno)
 
     def resolve_name(self, modname, parents, path, base):
-        """
+        """Resolve the module and name of the object to document given by the
-        Resolve the module and name of the object to document given by the
         arguments and the current module/class.
 
         Must return a pair of the module name and a chain of attributes; for
@@ -273,8 +271,7 @@ class Documenter(object):
         raise NotImplementedError('must be implemented in subclasses')
 
     def parse_name(self):
-        """
+        """Determine what module to import and what attribute to document.
-        Determine what module to import and what attribute to document.
 
         Returns True and sets *self.modname*, *self.objpath*, *self.fullname*,
         *self.args* and *self.retann* if parsing and resolving was successful.
@@ -311,8 +308,7 @@ class Documenter(object):
         return True
 
     def import_object(self):
-        """
+        """Import the object given by *self.modname* and *self.objpath* and set
-        Import the object given by *self.modname* and *self.objpath* and sets
         it as *self.object*.
 
         Returns True if successful, False if an error occurred.
@@ -338,15 +334,15 @@ class Documenter(object):
             return False
 
     def get_real_modname(self):
-        """
+        """Get the real module name of an object to document.
-        Get the real module name of an object to document.  (It can differ
+
-        from the name of the module through which the object was imported.)
+        It can differ from the name of the module through which the object was
+        imported.
         """
         return self.get_attr(self.object, '__module__', None) or self.modname
 
     def check_module(self):
-        """
+        """Check if *self.object* is really defined in the module given by
-        Check if *self.object* is really defined in the module given by
         *self.modname*.
         """
         modname = self.get_attr(self.object, '__module__', None)
@@ -355,25 +351,26 @@ class Documenter(object):
         return True
 
     def format_args(self):
-        """
+        """Format the argument signature of *self.object*.
-        Format the argument signature of *self.object*.  Should return None if
+
-        the object does not have a signature.
+        Should return None if the object does not have a signature.
         """
         return None
 
     def format_name(self):
-        """
+        """Format the name of *self.object*.
-        Format the name of *self.object*.  This normally should be something
+
-        that can be parsed by the generated directive, but doesn't need to be
+        This normally should be something that can be parsed by the generated
-        (Sphinx will display it unparsed then).
+        directive, but doesn't need to be (Sphinx will display it unparsed
+        then).
         """
         # normally the name doesn't contain the module (except for module
         # directives of course)
         return '.'.join(self.objpath) or self.modname
 
     def format_signature(self):
-        """
+        """Format the signature (arguments and return annotation) of the object.
-        Format the signature (arguments and return annotation) of the object.
+
         Let the user process it via the ``autodoc-process-signature`` event.
         """
         if self.args is not None:
@@ -473,8 +470,7 @@ class Documenter(object):
                 self.add_line(line, src[0], src[1])
 
     def get_object_members(self, want_all):
-        """
+        """Return `(members_check_module, members)` where `members` is a
-        Return `(members_check_module, members)` where `members` is a
         list of `(membername, member)` pairs of the members of *self.object*.
 
         If *want_all* is True, return all members.  Else, only return those
@@ -518,8 +514,9 @@ class Documenter(object):
         return False, sorted(members)
 
     def filter_members(self, members, want_all):
-        """
+        """Filter the given member list.
-        Filter the given member list: members are skipped if
+
+        Members are skipped if
 
         - they are private (except if given explicitly)
         - they are undocumented (except if undoc-members is given)
@@ -572,9 +569,10 @@ class Documenter(object):
         return ret
 
     def document_members(self, all_members=False):
-        """
+        """Generate reST for member documentation.
-        Generate reST for member documentation.  If *all_members* is True,
+
-        do all members, else those given by *self.options.members*.
+        If *all_members* is True, do all members, else those given by
+        *self.options.members*.
         """
         # set current namespace for finding members
         self.env.temp_data['autodoc:module'] = self.modname
@@ -632,8 +630,8 @@ class Documenter(object):
 
     def generate(self, more_content=None, real_modname=None,
                  check_module=False, all_members=False):
-        """
+        """Generate reST for the object given by *self.name*, and possibly for
-        Generate reST for the object given by *self.name*, and possibly members.
+        its members.
 
         If *more_content* is given, include that content. If *real_modname* is
         given, use that module name to find attribute docs. If *check_module* is

sphinx/ext/autosummary/__init__.py

@@ -73,8 +73,7 @@ class autosummary_toc(nodes.comment):
     pass
 
 def process_autosummary_toc(app, doctree):
-    """
+    """Insert items described in autosummary:: to the TOC tree, but do
-    Insert items described in autosummary:: to the TOC tree, but do
     not generate the toctree:: list.
     """
     env = app.builder.env
@@ -135,8 +134,8 @@ except AttributeError:
     isgetsetdescriptor = ismemberdescriptor
 
 def get_documenter(obj):
-    """
+    """Get an autodoc.Documenter class suitable for documenting the given
-    Get an autodoc.Documenter class suitable for documenting the given object
+    object.
     """
     import sphinx.ext.autodoc as autodoc
 
@@ -218,8 +217,7 @@ class Autosummary(Directive):
         return self.warnings + nodes
 
     def get_items(self, names):
-        """
+        """Try to import the given names, and return a list of
-        Try to import the given names, and return a list of
         ``[(name, signature, summary_string, real_name), ...]``.
         """
         env = self.state.document.settings.env
@@ -287,8 +285,7 @@ class Autosummary(Directive):
         return items
 
     def get_table(self, items):
-        """
+        """Generate a proper list of table nodes for autosummary:: directive.
-        Generate a proper list of table nodes for autosummary:: directive.
 
         *items* is a list produced by :meth:`get_items`.
         """
@@ -351,8 +348,7 @@ def mangle_signature(sig, max_chars=30):
     return u"(%s)" % sig
 
 def limited_join(sep, items, max_chars=30, overflow_marker="..."):
-    """
+    """Join a number of strings to one, limiting the length to *max_chars*.
-    Join a number of strings to one, limiting the length to *max_chars*.
 
     If the string overflows this limit, replace the last fitting item by
     *overflow_marker*.
@@ -377,8 +373,7 @@ def limited_join(sep, items, max_chars=30, overflow_marker="..."):
 # -- Importing items -----------------------------------------------------------
 
 def import_by_name(name, prefixes=[None]):
-    """
+    """Import a Python object that has the given *name*, under one of the
-    Import a Python object that has the given *name*, under one of the
     *prefixes*.  The first name that succeeds is used.
     """
     tried = []
@@ -435,8 +430,7 @@ def _import_by_name(name):
 
 def autolink_role(typ, rawtext, etext, lineno, inliner,
                   options={}, content=[]):
-    """
+    """Smart linking role.
-    Smart linking role.
 
     Expands to ':obj:`text`' if `text` is an object that can be imported;
     otherwise expands to '*text*'.

sphinx/ext/autosummary/generate.py

@@ -17,6 +17,7 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+
 import os
 import re
 import sys
@@ -193,8 +194,8 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
 # -- Finding documented entries in files ---------------------------------------
 
 def find_autosummary_in_files(filenames):
-    """
+    """Find out what items are documented in source/*.rst.
-    Find out what items are documented in source/*.rst.
+
     See `find_autosummary_in_lines`.
     """
     documented = []
@@ -206,8 +207,8 @@ def find_autosummary_in_files(filenames):
     return documented
 
 def find_autosummary_in_docstring(name, module=None, filename=None):
-    """
+    """Find out what items are documented in the given object's docstring.
-    Find out what items are documented in the given object's docstring.
+
     See `find_autosummary_in_lines`.
     """
     try:
@@ -221,8 +222,8 @@ def find_autosummary_in_docstring(name, module=None, filename=None):
     return []
 
 def find_autosummary_in_lines(lines, module=None, filename=None):
-    """
+    """Find out what items appear in autosummary:: directives in the
-    Find out what items appear in autosummary:: directives in the given lines.
+    given lines.
 
     Returns a list of (name, toctree, template) where *name* is a name
     of an object and *toctree* the :toctree: path of the corresponding

sphinx/ext/graphviz.py

@@ -89,9 +89,7 @@ class GraphvizSimple(Directive):
 
 
 def render_dot(self, code, options, format, prefix='graphviz'):
-    """
+    """Render graphviz code into a PNG or PDF output file."""
-    Render graphviz code into a PNG or PDF output file.
-    """
     hashkey = code.encode('utf-8') + str(options) + \
               str(self.builder.config.graphviz_dot) + \
               str(self.builder.config.graphviz_dot_args)

sphinx/ext/inheritance_diagram.py

@@ -67,8 +67,7 @@ class InheritanceGraph(object):
     graphviz dot graph from them.
     """
     def __init__(self, class_names, currmodule, show_builtins=False):
-        """
+        """*class_names* is a list of child classes to show bases from.
-        *class_names* is a list of child classes to show bases from.
 
         If *show_builtins* is True, then Python builtins will be shown
         in the graph.
@@ -82,9 +81,7 @@ class InheritanceGraph(object):
         self.show_builtins = show_builtins
 
     def _import_class_or_module(self, name, currmodule):
-        """
+        """Import a class using its fully-qualified *name*."""
-        Import a class using its fully-qualified *name*.
-        """
         try:
             path, base = class_sig_re.match(name).groups()
         except ValueError:
@@ -129,18 +126,14 @@ class InheritanceGraph(object):
                                    'not a class or module' % name)
 
     def _import_classes(self, class_names, currmodule):
-        """
+        """Import a list of classes."""
-        Import a list of classes.
-        """
         classes = []
         for name in class_names:
             classes.extend(self._import_class_or_module(name, currmodule))
         return classes
 
     def _all_classes(self, classes):
-        """
+        """Return a list of all classes that are ancestors of *classes*."""
-        Return a list of all classes that are ancestors of *classes*.
-        """
         all_classes = {}
 
         def recurse(cls):
@@ -155,10 +148,10 @@ class InheritanceGraph(object):
         return all_classes.keys()
 
     def class_name(self, cls, parts=0):
-        """
+        """Given a class object, return a fully-qualified name.
-        Given a class object, return a fully-qualified name.  This
+
-        works for things I've tested in matplotlib so far, but may not
+        This works for things I've tested in matplotlib so far, but may not be
-        be completely general.
+        completely general.
         """
         module = cls.__module__
         if module == '__builtin__':
@@ -171,9 +164,7 @@ class InheritanceGraph(object):
         return '.'.join(name_parts[-parts:])
 
     def get_all_class_names(self):
-        """
+        """Get all of the class names involved in the graph."""
-        Get all of the class names involved in the graph.
-        """
         return [self.class_name(x) for x in self.all_classes]
 
     # These are the default attrs for graphviz
@@ -202,9 +193,8 @@ class InheritanceGraph(object):
 
     def generate_dot(self, name, parts=0, urls={}, env=None,
                      graph_attrs={}, node_attrs={}, edge_attrs={}):
-        """
+        """Generate a graphviz dot graph from the classes that were passed in
-        Generate a graphviz dot graph from the classes that
+        to __init__.
-        were passed in to __init__.
 
         *name* is the name of the graph.
 

sphinx/ext/oldcmarkup.py

@@ -18,6 +18,7 @@ WARNING_MSG = 'using old C markup; please migrate to new-style markup ' \
               '(e.g. c:function instead of cfunction), see ' \
               'http://sphinx.pocoo.org/domains.html'
 
+
 class OldCDirective(Directive):
     has_content = True
     required_arguments = 1

sphinx/ext/pngmath.py

@@ -61,8 +61,7 @@ DOC_BODY_PREVIEW = r'''
 depth_re = re.compile(r'\[\d+ depth=(-?\d+)\]')
 
 def render_math(self, math):
-    """
+    """Render the LaTeX math expression *math* using latex and dvipng.
-    Render the LaTeX math expression *math* using latex and dvipng.
 
     Return the filename relative to the built document and the "depth",
     that is, the distance of image bottom and baseline in pixels, if the

sphinx/jinja2glue.py

@@ -37,8 +37,10 @@ def accesskey(context, key):
 
 
 class SphinxFileSystemLoader(FileSystemLoader):
-    """FileSystemLoader subclass that is not so strict about '..'
+    """
-    entries in template names."""
+    FileSystemLoader subclass that is not so strict about '..'  entries in
+    template names.
+    """
 
     def get_source(self, environment, template):
         for searchpath in self.searchpath:

sphinx/locale/__init__.py

@@ -15,8 +15,9 @@ import UserString
 
 
 class _TranslationProxy(UserString.UserString, object):
-    """Class for proxy strings from gettext translations.  This is a helper
+    """
-    for the lazy_* functions from this module.
+    Class for proxy strings from gettext translations.  This is a helper for the
+    lazy_* functions from this module.
 
     The proxy implementation attempts to be as complete as possible, so that
     the lazy objects should mostly work as expected, for example for sorting.
@@ -137,7 +138,8 @@ class _TranslationProxy(UserString.UserString, object):
 
 def mygettext(string):
     """Used instead of _ when creating TranslationProxies, because _ is
-    not bound yet at that time."""
+    not bound yet at that time.
+    """
     return _(string)
 
 def lazy_gettext(string):
@@ -189,8 +191,7 @@ else:
 
 
 def init(locale_dirs, language, catalog='sphinx'):
-    """
+    """Look for message catalogs in `locale_dirs` and *ensure* that there is at
-    Look for message catalogs in `locale_dirs` and *ensure* that there is at
     least a NullTranslations catalog set in `translators`.  If called multiple
     times or if several ``.mo`` files are found, their contents are merged
     together (thus making ``init`` reentrable).

sphinx/roles.py

@@ -139,16 +139,15 @@ class XRefRole(object):
     # methods that can be overwritten
 
     def process_link(self, env, refnode, has_explicit_title, title, target):
-        """
+        """Called after parsing title and target text, and creating the
-        Called after parsing title and target text, and creating the reference
+        reference node (given in *refnode*).  This method can alter the
-        node (given in *refnode*).  This method can alter the reference node and
+        reference node and must return a new (or the same) ``(title, target)``
-        must return a new (or the same) ``(title, target)`` tuple.
+        tuple.
         """
         return title, ws_re.sub(' ', target)
 
     def result_nodes(self, document, env, node, is_ref):
-        """
+        """Called before returning the finished nodes.  *node* is the reference
-        Called before returning the finished nodes.  *node* is the reference
         node if one was created (*is_ref* is then true), else the content node.
         This method can add other nodes and must return a ``(nodes, messages)``
         tuple (the usual return value of a role function).

sphinx/setup_command.py

@@ -22,7 +22,8 @@ from sphinx.util.console import darkred, nocolor, color_terminal
 
 
 class BuildDoc(Command):
-    """Distutils command to build Sphinx documentation.
+    """
+    Distutils command to build Sphinx documentation.
 
     The Sphinx build can then be triggered from distutils, and some Sphinx
     options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own

sphinx/theming.py

@@ -98,8 +98,7 @@ class Theme(object):
             self.base = Theme(inherit)
 
     def get_confstr(self, section, name, default=NODEFAULT):
-        """
+        """Return the value for a theme configuration setting, searching the
-        Return the value for a theme configuration setting, searching the
         base theme chain.
         """
         try:
@@ -114,9 +113,7 @@ class Theme(object):
                 return default
 
     def get_options(self, overrides):
-        """
+        """Return a dictionary of theme options and their values."""
-        Return a dictionary of theme options and their values.
-        """
         chain = [self.themeconf]
         base = self.base
         while base is not None:
@@ -135,8 +132,7 @@ class Theme(object):
         return options
 
     def get_dirchain(self):
-        """
+        """Return a list of theme directories, beginning with this theme's,
-        Return a list of theme directories, beginning with this theme's,
         then the base theme's, then that one's base theme's, etc.
         """
         chain = [self.themedir]
@@ -147,9 +143,7 @@ class Theme(object):
         return chain
 
     def cleanup(self):
-        """
+        """Remove temporary directories."""
-        Remove temporary directories.
-        """
         if self.themedir_created:
             try:
                 shutil.rmtree(self.themedir)

sphinx/util/__init__.py

@@ -50,8 +50,7 @@ def docname_join(basedocname, docname):
 
 
 def get_matching_files(dirname, exclude_matchers=()):
-    """
+    """Get all file names in a directory, recursively.
-    Get all file names in a directory, recursively.
 
     Exclude files and dirs matching some matcher in *exclude_matchers*.
     """
@@ -77,9 +76,8 @@ def get_matching_files(dirname, exclude_matchers=()):
 
 
 def get_matching_docs(dirname, suffix, exclude_matchers=()):
-    """
+    """Get all file names (without suffix) matching a suffix in a directory,
-    Get all file names (without suffix) matching a suffix in a
+    recursively.
-    directory, recursively.
 
     Exclude files and dirs matching a pattern in *exclude_patterns*.
     """
@@ -171,9 +169,7 @@ _DEBUG_HEADER = '''\
 '''
 
 def save_traceback():
-    """
+    """Save the current exception's traceback in a temporary file."""
-    Save the current exception's traceback in a temporary file.
-    """
     exc = traceback.format_exc()
     fd, path = tempfile.mkstemp('.log', 'sphinx-err-')
     os.write(fd, (_DEBUG_HEADER %
@@ -233,8 +229,7 @@ class Tee(object):
 
 
 def parselinenos(spec, total):
-    """
+    """Parse a line number spec (such as "1,2,4-6") and return a list of
-    Parse a line number spec (such as "1,2,4-6") and return a list of
     wanted line numbers.
     """
     items = list()
@@ -288,9 +283,7 @@ def rpartition(s, t):
 
 
 def format_exception_cut_frames(x=1):
-    """
+    """Format an exception with traceback, but only the last x frames."""
-    Format an exception with traceback, but only the last x frames.
-    """
     typ, val, tb = sys.exc_info()
     #res = ['Traceback (most recent call last):\n']
     res = []

sphinx/util/docstrings.py

@@ -13,11 +13,11 @@ import sys
 
 
 def prepare_docstring(s):
-    """
+    """Convert a docstring into lines of parseable reST.
-    Convert a docstring into lines of parseable reST.  Return it as a list of
+
-    lines usable for inserting into a docutils ViewList (used as argument
+    Return it as a list of lines usable for inserting into a docutils ViewList
-    of nested_parse().)  An empty line is added to act as a separator between
+    (used as argument of nested_parse().)  An empty line is added to act as a
-    this docstring and following content.
+    separator between this docstring and following content.
     """
     lines = s.expandtabs().splitlines()
     # Find minimum indentation of any non-blank lines after first line.
@@ -42,9 +42,8 @@ def prepare_docstring(s):
 
 
 def prepare_commentdoc(s):
-    """
+    """Extract documentation comment lines (starting with #:) and return them
-    Extract documentation comment lines (starting with #:) and return them as a
+    as a list of lines.  Returns an empty list if there is no documentation.
-    list of lines.  Returns an empty list if there is no documentation.
     """
     result = []
     lines = [line.strip() for line in s.expandtabs().splitlines()]

sphinx/util/jsonimpl.py

@@ -13,7 +13,7 @@ import UserString
 
 try:
     import json
-    # json-py's json module has not JSONEncoder; this will raise AttributeError
+    # json-py's json module has no JSONEncoder; this will raise AttributeError
     # if json-py is imported instead of the built-in json module
     JSONEncoder = json.JSONEncoder
 except (ImportError, AttributeError):

sphinx/util/matching.py

@@ -13,8 +13,7 @@ import re
 
 
 def _translate_pattern(pat):
-    """
+    """Translate a shell-style glob pattern to a regular expression.
-    Translate a shell-style glob pattern to a regular expression.
 
     Adapted from the fnmatch module, but enhanced so that single stars don't
     match slashes.
@@ -65,16 +64,14 @@ def compile_matchers(patterns):
 _pat_cache = {}
 
 def patmatch(name, pat):
-    """
+    """Return if name matches pat.  Adapted from fnmatch module."""
-    Return if name matches pat.  Adapted from fnmatch module.
-    """
     if pat not in _pat_cache:
         _pat_cache[pat] = re.compile(_translate_pattern(pat))
     return _pat_cache[pat].match(name)
 
 def patfilter(names, pat):
-    """
+    """Return the subset of the list NAMES that match PAT.
-    Return the subset of the list NAMES that match PAT.
+
     Adapted from fnmatch module.
     """
     if pat not in _pat_cache:

sphinx/util/nodes.py

@@ -38,6 +38,12 @@ def extract_messages(doctree):
 
 
 def nested_parse_with_titles(state, content, node):
+    """Version of state.nested_parse() that allows titles and does not require
+    titles to have the same decoration as the calling document.
+
+    This is useful when the parsed content comes from a completely different
+    context, such as docstrings.
+    """
     # hack around title style bookkeeping
     surrounding_title_styles = state.memo.title_styles
     surrounding_section_level = state.memo.section_level

sphinx/util/osutil.py

@@ -59,8 +59,8 @@ def ensuredir(path):
 
 
 def walk(top, topdown=True, followlinks=False):
-    """
+    """Backport of os.walk from 2.6, where the *followlinks* argument was
-    Backport of os.walk from 2.6, where the followlinks argument was added.
+    added.
     """
     names = os.listdir(top)
 

sphinx/util/png.py

@@ -21,9 +21,7 @@ IEND_CHUNK = '\x00\x00\x00\x00IEND\xAE\x42\x60\x82'
 
 
 def read_png_depth(filename):
-    """
+    """Read the special tEXt chunk indicating the depth from a PNG file."""
-    Read the special tEXt chunk indicating the depth from a PNG file.
-    """
     result = None
     f = open(filename, 'rb')
     try:
@@ -39,8 +37,8 @@ def read_png_depth(filename):
 
 
 def write_png_depth(filename, depth):
-    """
+    """Write the special tEXt chunk indicating the depth to a PNG file.
-    Write the special tEXt chunk indicating the depth to a PNG file.
+
     The chunk is placed immediately before the special IEND chunk.
     """
     data = struct.pack('!i', depth)

sphinx/util/websupport.py

@@ -6,5 +6,6 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+
 def is_commentable(node):
     return node.__class__.__name__ in ('paragraph', 'literal_block')

sphinx/writers/websupport.py

@@ -3,7 +3,7 @@
     sphinx.writers.websupport
     ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    docutils writers handling Sphinx' custom nodes.
+    sphinx.websupport writer that adds comment-related annotations.
 
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
@@ -12,6 +12,7 @@
 from sphinx.writers.html import HTMLTranslator
 from sphinx.util.websupport import is_commentable
 
+
 class WebSupportTranslator(HTMLTranslator):
     """
     Our custom HTML translator.