IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docstring harmonization.

Browse Source
This commit is contained in:
Georg Brandl 2010-08-22 11:36:08 +02:00
parent 2e47414658
commit 630791c42c
34 changed files with 233 additions and 285 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
sphinx/__init__.py
View File

@ -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')

19
sphinx/application.py
View File

@ -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 the configuration.
"""Load translated strings from the configured localedirs if 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 a
specified context (a Python dictionary).
"""Called by the builder to render a template given as a filename with
a 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')

43
sphinx/builders/__init__.py
View File

@ -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 (*typ* can be used to qualify
the link characteristic for individual builders).
"""Return the target URI for a document name.
*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. May raise
environment.NoUri if there's no way to return a sensible URI.
"""Return a relative URI between two source filenames.
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. First updates the environment, and then
calls :meth:`write`.
"""Main build method.
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. The default implementation does nothing.
"""Finish the building process.
The default implementation does nothing.
"""
pass
def cleanup(self):
"""
Cleanup any resources. The default implementation does nothing.
"""Cleanup any resources.
The default implementation does nothing.
"""
pass

1
sphinx/builders/devhelp.py
View File

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

32
sphinx/builders/epub.py
View File

@ -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.
For nested nodes the parent node is reinserted in the subnav.
Subelements of a node are nested inside the navpoint. For nested nodes
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
file properly escaped.
"""Create a dictionary with all metadata for the toc.ncx file
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
as the first entry.
It is a zip file with the mimetype file stored uncompressed as the first
entry.
"""
self.info('writing %s file...' % outname)
projectfiles = ['META-INF/container.xml', 'content.opf', 'toc.ncx'] \

3
sphinx/builders/html.py
View File

@ -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)

4
sphinx/config.py
View File

@ -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)

29
sphinx/domains/__init__.py
View File

@ -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 given,
restrict to entries referring to these docnames.
"""Return entries for the index given by *name*. If *docnames* is
given, 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)

25
sphinx/domains/cpp.py
View File

@ -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
a name you might call :meth:`split_owner` on.
"""Return the name.
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
owning parent. This function returns the owner and the
name as a tuple of two items. If a node does not support
it, :exc:`NotImplementedError` is raised.
"""Nodes returned by :meth:`get_name` can split off their owning parent.
This function returns the owner and the name as a tuple of two items.
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

2
sphinx/domains/javascript.py
View File

@ -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 '

22
sphinx/domains/python.py
View File

@ -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 signature.
"""May return a prefix to put before the object name in the
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.
Returns (fully qualified name of the thing, classname if any).
"""Transform a Python signature into RST nodes.
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 and/or
classname. Returns a list of (name, object entry) tuples.
"""Find a Python object for "name", perhaps using the given module
and/or classname. Returns a list of (name, object entry) tuples.
"""
# skip parens
if name[-2:] == '()':

7
sphinx/domains/rst.py
View File

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

73
sphinx/environment.py
View File

@ -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.
If base is True, return absolute path under self.srcdir.
If base is None, return relative path to self.srcdir.
If base is a path string, return absolute path under that.
If suffix is not None, add it instead of config.source_suffix.
"""Return the filename for the document name.
If *base* is True, return absolute path under self.srcdir.
If *base* is None, return relative path to self.srcdir.
If *base* is a path string, return absolute path under that.
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 self.found_docs.
"""Find all source files in the source dir and put them in
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. Returns a
summary, the total count of documents to reread and an iterator that
yields docnames as it processes them. Store all environment docnames in
the canonical format (ie using SEP as a separator in place of
os.path.sep).
"""(Re-)read all files new or changed since last update.
Returns a summary, the total count of documents to reread and an
iterator that yields docnames as it processes them. Store all
environment docnames in the canonical format (ie using SEP as a
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:

68
sphinx/ext/autodoc.py
View File

@ -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, lines
between lines that match the *marker* regular expression. If no line
"""Return a listener that either keeps, or if *exclude* is True excludes,
lines 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 sets
"""Import the object given by *self.modname* and *self.objpath* and set
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. (It can differ
from the name of the module through which the object was imported.)
"""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.
"""
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*. Should return None if
the object does not have a signature.
"""Format the argument signature of *self.object*.
Should return None if the object does not have a signature.
"""
return None
def format_name(self):
"""
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
(Sphinx will display it unparsed then).
"""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 (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: members are skipped if
"""Filter the given member list.
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. If *all_members* is True,
do all members, else those given by *self.options.members*.
"""Generate reST for member documentation.
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 members.
"""Generate reST for the object given by *self.name*, and possibly for
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

22
sphinx/ext/autosummary/__init__.py
View File

@ -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 object
"""Get an autodoc.Documenter class suitable for documenting the given
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*'.

13
sphinx/ext/autosummary/generate.py
View File

@ -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 given lines.
"""Find out what items appear in autosummary:: directives in the
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

4
sphinx/ext/graphviz.py
View File

@ -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)

32
sphinx/ext/inheritance_diagram.py
View File

@ -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. This
works for things I've tested in matplotlib so far, but may not
be completely general.
"""Given a class object, return a fully-qualified name.
This works for things I've tested in matplotlib so far, but may not be
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 to __init__.
"""Generate a graphviz dot graph from the classes that were passed in
to __init__.
*name* is the name of the graph.

1
sphinx/ext/oldcmarkup.py
View File

@ -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

3
sphinx/ext/pngmath.py
View File

@ -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

6
sphinx/jinja2glue.py
View File

@ -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:

11
sphinx/locale/__init__.py
View File

@ -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).

11
sphinx/roles.py
View File

@ -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 reference
node (given in *refnode*). This method can alter the reference node and
must return a new (or the same) ``(title, target)`` tuple.
"""Called after parsing title and target text, and creating the
reference node (given in *refnode*). This method can alter the
reference node and must return a new (or the same) ``(title, target)``
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).

3
sphinx/setup_command.py
View File

@ -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

14
sphinx/theming.py
View File

@ -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)

19
sphinx/util/__init__.py
View File

@ -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, recursively.
"""Get all file names (without suffix) matching a suffix in a 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 = []

15
sphinx/util/docstrings.py
View File

@ -13,11 +13,11 @@ import sys
def prepare_docstring(s):
"""
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
of nested_parse().) An empty line is added to act as a separator between
this docstring and following content.
"""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 of nested_parse().) An empty line is added to act as a
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 as a
list of lines. Returns an empty list if there is no documentation.
"""Extract documentation comment lines (starting with #:) and return them
as a list of lines. Returns an empty list if there is no documentation.
"""
result = []
lines = [line.strip() for line in s.expandtabs().splitlines()]

2
sphinx/util/jsonimpl.py
View File

@ -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):

11
sphinx/util/matching.py
View File

@ -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:

6
sphinx/util/nodes.py
View File

@ -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

4
sphinx/util/osutil.py
View File

@ -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 added.
"""Backport of os.walk from 2.6, where the *followlinks* argument was
added.
"""
names = os.listdir(top)

8
sphinx/util/png.py
View File

@ -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)

1
sphinx/util/websupport.py
View File

@ -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')

3
sphinx/writers/websupport.py
View File

@ -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.