diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 55abdb019..9d8c46901 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -25,6 +25,7 @@ class desc(nodes.Admonition, nodes.Element): contains one or more ``desc_signature`` and a ``desc_content``. """ + class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement): """Node for object signatures. @@ -39,33 +40,42 @@ class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement): # compatibility alias desc_classname = desc_addname + class desc_type(nodes.Part, nodes.Inline, nodes.TextElement): """Node for return types or object type names.""" + class desc_returns(desc_type): """Node for a "returns" annotation (a la -> in Python).""" def astext(self): return ' -> ' + nodes.TextElement.astext(self) + class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): """Node for the main object name.""" + class desc_parameterlist(nodes.Part, nodes.Inline, nodes.TextElement): """Node for a general parameter list.""" child_text_separator = ', ' + class desc_parameter(nodes.Part, nodes.Inline, nodes.TextElement): """Node for a single parameter.""" + class desc_optional(nodes.Part, nodes.Inline, nodes.TextElement): """Node for marking optional parts of the parameter list.""" child_text_separator = ', ' + def astext(self): return '[' + nodes.TextElement.astext(self) + ']' + class desc_annotation(nodes.Part, nodes.Inline, nodes.TextElement): """Node for signature annotations (not Python 3-style annotations).""" + class desc_content(nodes.General, nodes.Element): """Node for object description content. @@ -82,15 +92,18 @@ class versionmodified(nodes.Admonition, nodes.TextElement): directives. """ + class seealso(nodes.Admonition, nodes.Element): """Custom "see also" admonition.""" + class productionlist(nodes.Admonition, nodes.Element): """Node for grammar production lists. Contains ``production`` nodes. """ + class production(nodes.Part, nodes.Inline, nodes.TextElement): """Node for a single grammar production rule.""" @@ -107,26 +120,33 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement): *entrytype* is one of "single", "pair", "double", "triple". """ + class centered(nodes.Part, nodes.TextElement): """Deprecated.""" + class acks(nodes.Element): """Special node for "acks" lists.""" + class hlist(nodes.Element): """Node for "horizontal lists", i.e. lists that should be compressed to take up less vertical space. """ + class hlistcol(nodes.Element): """Node for one column in a horizontal list.""" + class compact_paragraph(nodes.paragraph): """Node for a compact paragraph (which never makes a

node).""" + class glossary(nodes.Element): """Node to insert a glossary.""" + class only(nodes.Element): """Node for "only" directives (conditional inclusion based on tags).""" @@ -136,14 +156,17 @@ class only(nodes.Element): class start_of_file(nodes.Element): """Node to mark start of a new file, used in the LaTeX builder only.""" + class highlightlang(nodes.Element): """Inserted to set the highlight language and line number options for subsequent code blocks. """ + class tabular_col_spec(nodes.Element): """Node for specifying tabular columns, used for LaTeX output.""" + class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): """Node for meta directive -- same as docutils' standard meta node, but pickleable. @@ -160,22 +183,27 @@ class pending_xref(nodes.Inline, nodes.Element): BuildEnvironment.resolve_references. """ + class download_reference(nodes.reference): """Node for download references, similar to pending_xref.""" + class literal_emphasis(nodes.emphasis): """Node that behaves like `emphasis`, but further text processors are not applied (e.g. smartypants for HTML output). """ + class literal_strong(nodes.strong): """Node that behaves like `strong`, but further text processors are not applied (e.g. smartypants for HTML output). """ + class abbreviation(nodes.Inline, nodes.TextElement): """Node for abbreviations with explanations.""" + class termsep(nodes.Structural, nodes.Element): """Separates two terms within a node.""" diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index f716286c7..7b1a96d25 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -88,7 +88,7 @@ def create_module_file(package, module, opts): text = format_heading(1, '%s module' % module) else: text = '' - #text += format_heading(2, ':mod:`%s` Module' % module) + # text += format_heading(2, ':mod:`%s` Module' % module) text += format_directive(module, package) write_file(makename(package, module), text, opts) @@ -173,7 +173,7 @@ def shall_skip(module, opts): # skip if it has a "private" name and this is selected filename = path.basename(module) if filename != '__init__.py' and filename.startswith('_') and \ - not opts.includeprivate: + not opts.includeprivate: return True return False @@ -218,7 +218,7 @@ def recurse_tree(rootpath, excludes, opts): if is_pkg: # we are in a package with something to document if subs or len(py_files) > 1 or not \ - shall_skip(path.join(root, INITPY), opts): + shall_skip(path.join(root, INITPY), opts): subpackage = root[len(rootpath):].lstrip(path.sep).\ replace(path.sep, '.') create_package_file(root, root_package, subpackage, @@ -318,7 +318,7 @@ Note: By default this script will not overwrite already created files.""") (opts, args) = parser.parse_args(argv[1:]) if opts.show_version: - print('Sphinx (sphinx-apidoc) %s' % __version__) + print('Sphinx (sphinx-apidoc) %s' % __version__) return 0 if not args: diff --git a/sphinx/application.py b/sphinx/application.py index fe8704018..6d30ab51a 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -200,8 +200,8 @@ class Sphinx(object): else: try: self.info(bold('loading pickled environment... '), nonl=True) - self.env = BuildEnvironment.frompickle(self.config, - path.join(self.doctreedir, ENV_PICKLE_FILENAME)) + self.env = BuildEnvironment.frompickle( + self.config, path.join(self.doctreedir, ENV_PICKLE_FILENAME)) self.env.domains = {} for domain in self.domains.keys(): # this can raise if the data version doesn't fit @@ -291,7 +291,7 @@ class Sphinx(object): else: location = None warntext = location and '%s: %s%s\n' % (location, prefix, message) or \ - '%s%s\n' % (prefix, message) + '%s%s\n' % (prefix, message) if self.warningiserror: raise SphinxWarning(warntext) self._warncount += 1 @@ -461,7 +461,7 @@ class Sphinx(object): else: raise ExtensionError( 'Builder %r already exists (in module %s)' % ( - builder.name, self.builderclasses[builder.name].__module__)) + builder.name, self.builderclasses[builder.name].__module__)) self.builderclasses[builder.name] = builder def add_config_value(self, name, default, rebuild): diff --git a/sphinx/environment.py b/sphinx/environment.py index 648e22565..8e94ef4ea 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -503,7 +503,8 @@ class BuildEnvironment: """Custom decoding error handler that warns and replaces.""" linestart = error.object.rfind(b'\n', 0, error.start) lineend = error.object.find(b'\n', error.start) - if lineend == -1: lineend = len(error.object) + if lineend == -1: + lineend = len(error.object) lineno = error.object.count(b'\n', 0, error.start) + 1 self.warn(self.docname, 'undecodable source characters, ' 'replacing with "?": %r' % diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index fdfb81062..f81b38f05 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -10,13 +10,16 @@ """ from __future__ import print_function -import sys, os, time, re +import re +import os +import sys +import time from os import path from io import open TERM_ENCODING = getattr(sys.stdin, 'encoding', None) -#try to import readline, unix specific enhancement +# try to import readline, unix specific enhancement try: import readline if readline.__doc__ and 'libedit' in readline.__doc__: @@ -33,7 +36,7 @@ from docutils.utils import column_width from sphinx import __version__ from sphinx.util.osutil import make_filename from sphinx.util.console import purple, bold, red, turquoise, \ - nocolor, color_terminal + nocolor, color_terminal from sphinx.util import texescape # function to get input from terminal -- overridden by the test suite @@ -972,17 +975,20 @@ def mkdir_p(dir): class ValidationError(Exception): """Raised for validation errors.""" + def is_path(x): x = path.expanduser(x) if path.exists(x) and not path.isdir(x): raise ValidationError("Please enter a valid path name.") return x + def nonempty(x): if not x: raise ValidationError("Please enter some text.") return x + def choice(*l): def val(x): if x not in l: @@ -990,17 +996,20 @@ def choice(*l): return x return val + def boolean(x): if x.upper() not in ('Y', 'YES', 'N', 'NO'): raise ValidationError("Please enter either 'y' or 'n'.") return x.upper() in ('Y', 'YES') + def suffix(x): if not (x[0:1] == '.' and len(x) > 1): raise ValidationError("Please enter a file suffix, " "e.g. '.rst' or '.txt'.") return x + def ok(x): return x @@ -1097,7 +1106,7 @@ Enter the root path for documentation.''') do_prompt(d, 'path', 'Root path for the documentation', '.', is_path) while path.isfile(path.join(d['path'], 'conf.py')) or \ - path.isfile(path.join(d['path'], 'source', 'conf.py')): + path.isfile(path.join(d['path'], 'source', 'conf.py')): print() print(bold('Error: an existing conf.py has been found in the ' 'selected root path.')) @@ -1169,7 +1178,7 @@ document is a custom template, you can also set this to another filename.''') 'index') while path.isfile(path.join(d['path'], d['master']+d['suffix'])) or \ - path.isfile(path.join(d['path'], 'source', d['master']+d['suffix'])): + path.isfile(path.join(d['path'], 'source', d['master']+d['suffix'])): print() print(bold('Error: the master file %s has already been found in the ' 'selected root path.' % (d['master']+d['suffix']))) @@ -1256,10 +1265,10 @@ def generate(d, overwrite=True, silent=False): d['extensions'] = extensions d['copyright'] = time.strftime('%Y') + ', ' + d['author'] d['author_texescaped'] = text_type(d['author']).\ - translate(texescape.tex_escape_map) + translate(texescape.tex_escape_map) d['project_doc'] = d['project'] + ' Documentation' d['project_doc_texescaped'] = text_type(d['project'] + ' Documentation').\ - translate(texescape.tex_escape_map) + translate(texescape.tex_escape_map) # escape backslashes and single quotes in strings that are put into # a Python string literal diff --git a/sphinx/roles.py b/sphinx/roles.py index 729dcea05..451cfe60b 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -236,6 +236,7 @@ def indexmarkup_role(typ, rawtext, text, lineno, inliner, _amp_re = re.compile(r'(?