From d6063ff35b19fc36ee2c4ba022a1e12dbcbbdaed Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 30 May 2019 01:07:05 +0900 Subject: [PATCH] doc: Fold lines by 80 columns --- CHANGES | 228 ++++++++++++++----------- CONTRIBUTING.rst | 4 +- doc/development/tutorials/todo.rst | 4 +- doc/extdev/i18n.rst | 2 +- doc/extdev/index.rst | 6 +- doc/templating.rst | 3 +- doc/usage/extensions/graphviz.rst | 4 +- doc/usage/extensions/ifconfig.rst | 6 +- doc/usage/restructuredtext/domains.rst | 5 +- utils/doclinter.py | 2 +- 10 files changed, 149 insertions(+), 115 deletions(-) diff --git a/CHANGES b/CHANGES index aae8df0e550..61ee0854850 100644 --- a/CHANGES +++ b/CHANGES @@ -148,7 +148,8 @@ Bugs fixed - sphinx.builders.htmlhelp - :confval:`viewcode_import` -* #6208: C++, properly parse full xrefs that happen to have a short xref as prefix. +* #6208: C++, properly parse full xrefs that happen to have a short xref as + prefix * #6220, #6225: napoleon: AttributeError is raised for raised section having references * #6245: circular import error on importing SerializingHTMLBuilder @@ -449,7 +450,8 @@ Release 1.8.5 (released Mar 10, 2019) Bugs fixed ---------- -* LaTeX: Remove extraneous space after author names on PDF title page (refs: #6004) +* LaTeX: Remove extraneous space after author names on PDF title page (refs: + #6004) * #6026: LaTeX: A cross reference to definition list does not work * #6046: LaTeX: ``TypeError`` is raised when invalid latex_elements given * #6067: LaTeX: images having a target are concatenated to next line @@ -477,8 +479,8 @@ Bugs fixed * #5889: LaTeX: user ``numfig_format`` is stripped of spaces and may cause build failure * C++, fix hyperlinks for declarations involving east cv-qualifiers. -* #5755: C++, fix duplicate declaration error on function templates with constraints - in the return type. +* #5755: C++, fix duplicate declaration error on function templates with + constraints in the return type. * C++, parse unary right fold expressions and binary fold expressions. * pycode could not handle egg files on windows * #5928: KeyError: 'DOCUTILSCONFIG' when running build @@ -721,7 +723,8 @@ Deprecated * ``sphinx.writers.latex.Table.caption_footnotetexts`` is deprecated * ``sphinx.writers.latex.Table.header_footnotetexts`` is deprecated * ``sphinx.writers.latex.LaTeXTranslator.footnotestack`` is deprecated -* ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block`` is deprecated +* ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block`` is + deprecated * ``sphinx.writers.latex.LaTeXTranslator.next_section_ids`` is deprecated * ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids`` is deprecated * ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()`` is deprecated @@ -806,12 +809,13 @@ Features added - Add a ``cpp:texpr`` role as a sibling to ``cpp:expr``. - Add support for unions. - - #3593, #2683: add support for anonymous entities using names staring with ``@``. + - #3593, #2683: add support for anonymous entities using names staring with + ``@``. - #5147: add support for (most) character literals. - Cross-referencing entities inside primary templates is supported, and now properly documented. - - #1552: add new cross-referencing format for ``cpp:any`` and ``cpp:func`` roles, - for referencing specific function overloads. + - #1552: add new cross-referencing format for ``cpp:any`` and ``cpp:func`` + roles, for referencing specific function overloads. * #3606: MathJax should be loaded with async attribute * html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set (refs: @@ -868,7 +872,7 @@ Bugs fixed * #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu. * #4983: productionlist directive generates invalid IDs for the tokens -* #5132: (lualatex) PDF build fails if indexed word starts with Unicode character +* #5132: lualatex: PDF build fails if indexed word starts with Unicode character * #5133: latex: index headings "Symbols" and "Numbers" not internationalized * #5114: sphinx-build: Handle errors on scanning documents * epub: spine has been broken when "self" is listed on toctree (refs: #4611) @@ -1196,19 +1200,21 @@ Features added 1.7.0b1 * C++, handle ``decltype(auto)``. -* #2406: C++, add proper parsing of expressions, including linking of identifiers. +* #2406: C++, add proper parsing of expressions, including linking of + identifiers. * C++, add a ``cpp:expr`` role for inserting inline C++ expressions or types. -* C++, support explicit member instantiations with shorthand ``template`` prefix. +* C++, support explicit member instantiations with shorthand ``template`` prefix * C++, make function parameters linkable, like template params. * #3638: Allow to change a label of reference to equation using ``math_eqref_format`` - * Now :confval:`suppress_warnings` accepts following configurations: - ``ref.python`` (ref: #3866) + * #3872: Add latex key to configure literal blocks caption position in PDF output (refs #3792, #1723) -* In case of missing docstring try to retrieve doc from base classes (ref: #3140) +* In case of missing docstring try to retrieve doc from base classes (ref: + #3140) * #4023: Clarify error message when any role has more than one target. * #3973: epub: allow to override build date * #3972: epub: Sort manifest entries by filename @@ -1396,8 +1402,8 @@ Bugs fixed remote image * #1421: Respect the quiet flag in sphinx-quickstart * #4281: Race conditions when creating output directory -* #4315: For PDF 'howto' documents, ``latex_toplevel_sectioning='part'`` generates - ``\chapter`` commands +* #4315: For PDF 'howto' documents, ``latex_toplevel_sectioning='part'`` + generates ``\chapter`` commands * #4214: Two todolist directives break sphinx-1.6.5 * Fix links to external option docs with intersphinx (refs: #3769) * #4091: Private members not documented without :undoc-members: @@ -1565,16 +1571,19 @@ Incompatible changes * #1061, #2336, #3235: Now generation of autosummary doesn't contain imported members by default. Thanks to Luc Saffre. -* LaTeX ``\includegraphics`` command isn't overloaded: only ``\sphinxincludegraphics`` - has the custom code to fit image to available width if oversized. +* LaTeX ``\includegraphics`` command isn't overloaded: only + ``\sphinxincludegraphics`` has the custom code to fit image to available width + if oversized. * The subclasses of ``sphinx.domains.Index`` should override ``generate()`` method. The default implementation raises NotImplementedError * LaTeX positioned long tables horizontally centered, and short ones - flushed left (no text flow around table.) The position now defaults to center in - both cases, and it will obey Docutils 0.13 ``:align:`` option (refs #3415, #3377) -* option directive also allows all punctuations for the option name (refs: #3366) -* #3413: if :rst:dir:`literalinclude`'s ``:start-after:`` is used, make ``:lines:`` - relative (refs #3412) + flushed left (no text flow around table.) The position now defaults to center + in both cases, and it will obey Docutils 0.13 ``:align:`` option (refs #3415, + #3377) +* option directive also allows all punctuations for the option name (refs: + #3366) +* #3413: if :rst:dir:`literalinclude`'s ``:start-after:`` is used, make + ``:lines:`` relative (refs #3412) * ``literalinclude`` directive does not allow the combination of ``:diff:`` option and other options (refs: #3416) * LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine @@ -1582,7 +1591,8 @@ Incompatible changes * :confval:`latex_keep_old_macro_names` default value has been changed from ``True`` to ``False``. This means that some LaTeX macros for styling are by default defined only with ``\sphinx..`` prefixed names. (refs: #3429) -* Footer "Continued on next page" of LaTeX longtable's now not framed (refs: #3497) +* Footer "Continued on next page" of LaTeX longtable's now not framed (refs: + #3497) * #3529: The arguments of ``BuildEnvironment.__init__`` is changed * #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms only) * #3558: Emit warnings if footnotes and citations are not referenced. The @@ -1643,8 +1653,8 @@ Features added 1.6b1 * #3136: Add ``:name:`` option to the directives in ``sphinx.ext.graphviz`` -* #2336: Add ``imported_members`` option to ``sphinx-autogen`` command to document - imported members. +* #2336: Add ``imported_members`` option to ``sphinx-autogen`` command to + document imported members. * C++, add ``:tparam-line-spec:`` option to templated declarations. When specified, each template parameter will be rendered on a separate line. * #3359: Allow sphinx.js in a user locale dir to override sphinx.js from Sphinx @@ -1670,7 +1680,8 @@ Features added * HTML builder uses experimental HTML5 writer if ``html_experimental_html5_writer`` is True and docutils 0.13 or later is installed. -* LaTeX macros to customize space before and after tables in PDF output (refs #3504) +* LaTeX macros to customize space before and after tables in PDF output (refs + #3504) * #3348: Show decorators in literalinclude and viewcode directives * #3108: Show warning if :start-at: and other literalinclude options does not match to the text @@ -1733,7 +1744,7 @@ Bugs fixed :confval:`html_compact_lists` is True. * The ``make latexpdf`` from 1.6b1 (for GNU/Linux and Mac OS, using ``latexmk``) aborted earlier in case of LaTeX errors than was the case with - 1.5 series, due to hard-coded usage of ``--halt-on-error`` option. (refs #3695) + 1.5 series, due to hard-coded usage of ``--halt-on-error`` option (refs #3695) * #3683: sphinx.websupport module is not provided by default * #3683: Failed to build document if builder.css_file.insert() is called * #3714: viewcode extension not taking ``highlight_code='none'`` in account @@ -1868,7 +1879,8 @@ Bugs fixed * #3507: wrong quotes in latex output for productionlist directive * #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links rendered as code -* #2665, #2607: Link names in C++ docfields, and make it possible for other domains. +* #2665, #2607: Link names in C++ docfields, and make it possible for other + domains. * #3542: C++, fix parsing error of non-type template argument with template. * #3065, #3520: python domain fails to recognize nested class * #3575: Problems with pdflatex in a Turkish document built with sphinx has @@ -1948,7 +1960,7 @@ Bugs fixed unserializable exception * #3315: Bibliography crashes on latex build with docclass 'memoir' * #3328: Could not refer rubric implicitly -* #3329: emit warnings if po file is invalid and can't read it. Also writing mo too +* #3329: emit warnings if po file is invalid and can't read it. Also writing mo * #3337: Ugly rendering of definition list term's classifier * #3335: gettext does not extract field_name of a field in a field_list * #2952: C++, fix refs to operator() functions. @@ -1966,7 +1978,8 @@ Bugs fixed * #3308: Parsed-literals don't wrap very long lines with pdf builder (ref #3340) * #3295: Could not import extension sphinx.builders.linkcheck * #3285: autosummary: asterisks are escaped twice -* LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref #3363) +* LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref + #3363) * Fix parselinenos() could not parse left half open range (cf. "-4") @@ -2024,8 +2037,8 @@ Incompatible changes ``index.rst.txt``). * ``sphinx.util.copy_static_entry()`` is now deprecated. Use ``sphinx.util.fileutil.copy_asset()`` instead. -* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been changed - (ref: #2510, #2753) +* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been + changed (ref: #2510, #2753) * Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773) * QtHelpBuilder doesn't generate search page (ref: #2352) @@ -2186,8 +2199,9 @@ Features added * #2513: A better default settings for XeLaTeX * #3096: ``'maxlistdepth'`` key to work around LaTeX list limitations -* #3060: autodoc supports documentation for attributes of Enum class. Now autodoc render - just the value of Enum attributes instead of Enum attribute representation. +* #3060: autodoc supports documentation for attributes of Enum class. Now + autodoc render just the value of Enum attributes instead of Enum attribute + representation. * Add ``--extensions`` to ``sphinx-quickstart`` to support enable arbitrary extensions from command line (ref: #2904) * #3104, #3122: ``'sphinxsetup'`` for key=value styling of Sphinx LaTeX @@ -2197,7 +2211,8 @@ Features added :confval:`linkcheck_anchors_ignore` * #3083: let Unicode no-break space act like LaTeX ``~`` (fixed #3019) * #3116: allow word wrap in PDF output for inline literals (ref #3110) -* #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to Nick Coghlan. +* #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to Nick + Coghlan. * #3121: add ``inlineliteralwraps`` option to control if inline literal word-wraps in latex @@ -2259,12 +2274,14 @@ Bugs fixed 1.5b1 -* #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex Grönholm. +* #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex + Grönholm. * #3062: Failed to build PDF using 1.5a2 (undefined ``\hypersetup`` for Japanese documents since PR#3030) * Better rendering of multiline signatures in html. * #777: LaTeX output "too deeply nested" (ref #3096) -* Let LaTeX image inclusion obey ``scale`` before textwidth fit (ref #2865, #3059) +* Let LaTeX image inclusion obey ``scale`` before textwidth fit (ref #2865, + #3059) * #3019: LaTeX fails on description of C function with arguments (ref #3083) * fix latex inline literals where ``< > -`` gobbled a space @@ -2284,8 +2301,8 @@ Bugs fixed * #1843: Fix documentation of descriptor classes that have a custom metaclass. Thanks to Erik Bray. * #3190: util.split_docinfo fails to parse multi-line field bodies -* #3024, #3037: In Python3, application.Sphinx._log crushed when the log message cannot - be encoded into console encoding. +* #3024, #3037: In Python3, application.Sphinx._log crushed when the log message + cannot be encoded into console encoding. Testing -------- @@ -2404,7 +2421,7 @@ Features added -------------- * new config option ``latex_keep_old_macro_names``, defaults to True. If False, - lets macros (for text styling) be defined only with ``\sphinx``-prefixed names. + lets macros (for text styling) be defined only with ``\sphinx``-prefixed names * latex writer allows user customization of "shadowed" boxes (topics), via three length variables. * woff-format web font files now supported by the epub builder. @@ -2746,11 +2763,12 @@ Bugs fixed * C++, fix parsing of types prefixed with 'enum'. * #2023: Dutch search support uses Danish stemming info. * C++, add support for user-defined literals. -* #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks to - Hassen ben tanfous. +* #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks + to Hassen ben tanfous. * #2183: Fix porterstemmer causes ``make json`` to fail. * #1899: Ensure list is sent to OptParse. -* #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package option). +* #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package + option). * #2165, #2218: Remove faulty and non-need conditional from sphinx.sty. * Fix broken LaTeX code is generated if unknown language is given * #1944: Fix rst_prolog breaks file-wide metadata @@ -2763,12 +2781,13 @@ Bugs fixed * Fix ValueError is raised if LANGUAGE is empty string * Fix unpack warning is shown when the directives generated from ``Sphinx.add_crossref_type`` is used -* The default highlight language is now ``default``. This means that source code - is highlighted as Python 3 (which is mostly a superset of Python 2) if possible. - To get the old behavior back, add ``highlight_language = "python"`` to conf.py. +* The default highlight language is now ``default``. This means that source + code is highlighted as Python 3 (which is mostly a superset of Python 2) if + possible. To get the old behavior back, add ``highlight_language = "python"`` + to conf.py. * #2329: Refresh environment forcedly if source directory has changed. -* #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option from - xcolor package +* #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option + from xcolor package * Fix the confval type checker emits warnings if unicode is given to confvals which expects string value * #2360: Fix numref in LaTeX output is broken @@ -2776,20 +2795,24 @@ Bugs fixed * #2364: Fix KeyError 'rootSymbol' on Sphinx upgrade from older version. * #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer. * #2368: Ignore emacs lock files like ``.#foo.rst`` by default. -* #2262: literal_block and its caption has been separated by pagebreak in LaTeX output. -* #2319: Fix table counter is overridden by code-block's in LaTeX. Thanks to jfbu. +* #2262: literal_block and its caption has been separated by pagebreak in LaTeX + output. +* #2319: Fix table counter is overridden by code-block's in LaTeX. Thanks to + jfbu. * Fix unpack warning if combined with 3rd party domain extensions. * #1153: Fix figures in sidebar causes latex build error. * #2358: Fix user-preamble could not override the tocdepth definition. -* #2358: Reduce tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel. +* #2358: Reduce tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel * #2351: Fix footnote spacing -* #2363: Fix ``toctree()`` in templates generates broken links in SingleHTMLBuilder. +* #2363: Fix ``toctree()`` in templates generates broken links in + SingleHTMLBuilder. * #2366: Fix empty hyperref is generated on toctree in HTML builder. Documentation ------------- -* #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf Hemmecke. +* #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf + Hemmecke. Release 1.3.6 (released Feb 29, 2016) @@ -2798,8 +2821,9 @@ Release 1.3.6 (released Feb 29, 2016) Features added -------------- -* #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This should be - introduced with :confval:`source_parsers` feature. Thanks for Eric Holscher. +* #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This + should be introduced with :confval:`source_parsers` feature. Thanks for Eric + Holscher. Bugs fixed @@ -2835,11 +2859,11 @@ Bugs fixed * #2243: Ignore strange docstring types for classes, do not crash * #2247: Fix #2205 breaks make html for definition list with classifiers that contains regular-expression like string -* #1565: Sphinx will now emit a warning that highlighting was skipped if the syntax - is incorrect for `code-block`, `literalinclude` and so on. +* #1565: Sphinx will now emit a warning that highlighting was skipped if the + syntax is incorrect for `code-block`, `literalinclude` and so on. * #2211: Fix paragraphs in table cell doesn't work in Latex output -* #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect indented - body block when the block starts with blank or comment lines. +* #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect + indented body block when the block starts with blank or comment lines. * Fix TOC is not shown when no ``:maxdepth:`` for toctrees (ref: #771) * Fix warning message for ``:numref:`` if target is in orphaned doc (ref: #2244) @@ -2878,7 +2902,8 @@ Bugs fixed and link is broken * #2197: Fix slightly cryptic error message for missing index.rst file * #1894: Unlisted phony targets in quickstart Makefile -* #2125: Fix unifies behavior of collapsed fields (``GroupedField`` and ``TypedField``) +* #2125: Fix unifies behavior of collapsed fields (``GroupedField`` and + ``TypedField``) * #1408: Check latex_logo validity before copying * #771: Fix latex output doesn't set tocdepth * #1820: On Windows, console coloring is broken with colorama version 0.3.3. @@ -2896,9 +2921,9 @@ Bugs fixed * #2062: Escape characters in doctests are treated incorrectly with Python 2. * #2225: Fix if the option does not begin with dash, linking is not performed * #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax) -* #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions doesn't - support resolve_any_xref and resolve_xref returns problematic node instead of None. - sphinxcontrib-httpdomain is one of them. +* #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions + doesn't support resolve_any_xref and resolve_xref returns problematic node + instead of None. sphinxcontrib-httpdomain is one of them. * #2229: Fix no warning is given for unknown options Release 1.3.3 (released Dec 2, 2015) @@ -2909,8 +2934,8 @@ Bugs fixed * #2177: Fix parallel hangs * #2012: Fix exception occurred if ``numfig_format`` is invalid -* #2142: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` for - source distribution on PyPI. +* #2142: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` + for source distribution on PyPI. * #2148: Error while building devhelp target with non-ASCII document. @@ -2925,24 +2950,27 @@ Features added Bugs fixed ---------- -* #1976: Avoid "2.0" version of Babel because it doesn't work with Windows environment. -* Add a "default.css" stylesheet (which imports "classic.css") for compatibility. +* #1976: Avoid "2.0" version of Babel because it doesn't work with Windows + environment. +* Add a "default.css" stylesheet (which imports "classic.css") for compatibility * #1788: graphviz extension raises exception when caption option is present. -* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes following - lines after class definitions +* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes + following lines after class definitions * #1790: ``literalinclude`` strips empty lines at the head and tail -* #1802: load plugin themes automatically when theme.conf use it as 'inherit'. Thanks to - Takayuki Hirai. -* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find base theme. +* #1802: load plugin themes automatically when theme.conf use it as 'inherit'. + Thanks to Takayuki Hirai. +* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find + base theme. * #1834: compatibility for docutils-0.13: handle_io_errors keyword argument for docutils.io.FileInput cause TypeError. -* #1823: '.' as for sphinx-apidoc cause an unfriendly error. Now '.' - is converted to absolute path automatically. +* #1823: '.' as for sphinx-apidoc cause an unfriendly error. Now + '.' is converted to absolute path automatically. * Fix a crash when setting up extensions which do not support metadata. * #1784: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` -* #1822, #1892: Fix regression for #1061. autosummary can't generate doc for imported - members since sphinx-1.3b3. Thanks to Eric Larson. -* #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki Hirai. +* #1822, #1892: Fix regression for #1061. autosummary can't generate doc for + imported members since sphinx-1.3b3. Thanks to Eric Larson. +* #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki + Hirai. * #1780, #1866: "make text" shows "class" keyword twice. Thanks to Takayuki Hirai. * #1871: Fix for LaTeX output of tables with one column and multirows. @@ -2976,8 +3004,8 @@ Bugs fixed Sphinx-1.3.0/1.3.1. * On Py2 environment, conf.py that is generated by sphinx-quickstart should have u prefixed config value for 'version' and 'release'. -* #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will raise - UnicodeEncodeError. +* #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will + raise UnicodeEncodeError. * #1974: UnboundLocalError: local variable 'domain' referenced before assignment when using `any` role and `sphinx.ext.intersphinx` in same time. * #2121: multiple words search doesn't find pages when words across on the page @@ -3001,7 +3029,8 @@ Bugs fixed * #1769: allows generating quickstart files/dirs for destination dir that doesn't overwrite existent files/dirs. Thanks to WAKAYAMA shirou. -* #1773: sphinx-quickstart doesn't accept non-ASCII character as a option argument. +* #1773: sphinx-quickstart doesn't accept non-ASCII character as a option + argument. * #1766: the message "least Python 2.6 to run" is at best misleading. * #1772: cross reference in docstrings like ``:param .write:`` breaks building. * #1770, #1774: ``literalinclude`` with empty file occurs exception. Thanks to @@ -3051,10 +3080,11 @@ Bugs fixed begin with -, / or +. Thanks to Takayuki Hirai. * #1753: C++, added missing support for more complex declarations. * #1700: Add ``:caption:`` option for :rst:dir:`toctree`. -* #1742: ``:name:`` option is provided for :rst:dir:`toctree`, :rst:dir:`code-block` - and :rst:dir:`literalinclude` directives. +* #1742: ``:name:`` option is provided for :rst:dir:`toctree`, + :rst:dir:`code-block` and :rst:dir:`literalinclude` directives. * #1756: Incorrect section titles in search that was introduced from 1.3b3. -* #1746: C++, fixed name lookup procedure, and added missing lookups in declarations. +* #1746: C++, fixed name lookup procedure, and added missing lookups in + declarations. * #1765: C++, fix old id generation to use fully qualified names. Documentation @@ -3121,14 +3151,16 @@ Bugs fixed * #1690: toctrees with ``glob`` option now can also contain entries for single documents with explicit title. * #1591: html search results for C++ elements now has correct interpage links. -* bizstyle theme: nested long title pages make long breadcrumb that breaks page layout. +* bizstyle theme: nested long title pages make long breadcrumb that breaks page + layout. * bizstyle theme: all breadcrumb items become 'Top' on some mobile browser (iPhone5s safari). -* #1722: restore ``toctree()`` template function behavior that was changed at 1.3b1. +* #1722: restore ``toctree()`` template function behavior that was changed at + 1.3b1. * #1732: i18n: localized table caption raises exception. * #1718: ``:numref:`` does not work with capital letters in the label -* #1630: resolve CSS conflicts, ``div.container`` css target for literal block wrapper - now renamed to ``div.literal-block-wrapper``. +* #1630: resolve CSS conflicts, ``div.container`` css target for literal block + wrapper now renamed to ``div.literal-block-wrapper``. * ``sphinx.util.pycompat`` has been restored in its backwards-compatibility; slated for removal in Sphinx 1.4. * #1719: LaTeX writer does not respect ``numref_format`` option in captions @@ -3362,8 +3394,8 @@ Release 1.2.3 (released Sep 1, 2014) Features added -------------- -* #1518: ``sphinx-apidoc`` command now has a ``--version`` option to show version - information and exit +* #1518: ``sphinx-apidoc`` command now has a ``--version`` option to show + version information and exit * New locales: Hebrew, European Portuguese, Vietnamese. Bugs fixed @@ -3705,17 +3737,17 @@ Features added template function has been fixed (bug #1046). - PR#99: Strip down seealso directives to normal admonitions. This removes their unusual CSS classes (admonition-see-also), inconsistent LaTeX - admonition title ("See Also" instead of "See also"), and spurious indentation - in the text builder. + admonition title ("See Also" instead of "See also"), and spurious + indentation in the text builder. * HTML builder - #783: Create a link to full size image if it is scaled with width or height. - - #1067: Improve the ordering of the JavaScript search results: matches in titles - come before matches in full text, and object results are better categorized. - Also implement a pluggable search scorer. - - #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now work - together. + - #1067: Improve the ordering of the JavaScript search results: matches in + titles come before matches in full text, and object results are better + categorized. Also implement a pluggable search scorer. + - #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now + work together. - Update to jQuery 1.7.1 and Underscore.js 1.3.1. * Texinfo builder @@ -4413,8 +4445,8 @@ Features added * General: - Added a "nitpicky" mode that emits warnings for all missing - references. It is activated by the :option:`sphinx-build -n` command-line switch - or the `nitpicky` config value. + references. It is activated by the :option:`sphinx-build -n` command-line + switch or the `nitpicky` config value. - Added ``latexpdf`` target in quickstart Makefile. * Markup: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1ca1fc608c8..1807d3998cc 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -303,8 +303,8 @@ Debugging Tips * Set the debugging options in the `Docutils configuration file `_. -* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) are - generated by this +* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) + are generated by this `modified snowballcode generator `_. Generated `JSX `_ files are in `this repository `_. diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index 78a37c2fe12..f4ac85ac943 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/todo.rst @@ -23,8 +23,8 @@ We want the extension to add the following to Sphinx: only shown in the output if a new config value is set. Todo entries should not be in the output by default. -* A ``todolist`` directive that creates a list of all todo entries throughout the - documentation. +* A ``todolist`` directive that creates a list of all todo entries throughout + the documentation. For that, we will need to add the following elements to Sphinx: diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst index c3ec173a26f..a3232b85768 100644 --- a/doc/extdev/i18n.rst +++ b/doc/extdev/i18n.rst @@ -19,7 +19,7 @@ i18n API .. _ext-i18n: Extension internationalization (`i18n`) and localization (`l10n`) using i18n API ---------------------------------------------------------------------------------- +-------------------------------------------------------------------------------- .. versionadded:: 1.8 diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index c70ca37be2c..8c909e31504 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -144,9 +144,9 @@ in which a Sphinx project is built: this works in several phases. Now that the metadata and cross-reference data of all existing documents is known, all temporary nodes are replaced by nodes that can be converted into - output using components called transforms. For example, links are created for - object references that exist, and simple literal nodes are created for those - that don't. + output using components called transforms. For example, links are created + for object references that exist, and simple literal nodes are created for + those that don't. **Phase 4: Writing** diff --git a/doc/templating.rst b/doc/templating.rst index 3790275f5ea..14fb31ed89c 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -297,7 +297,8 @@ in the future. The "page name" of the current file, i.e. either the document name if the file is generated from a reST source, or the equivalent hierarchical name - relative to the output directory (``[directory/]filename_without_extension``). + relative to the output directory + (``[directory/]filename_without_extension``). .. data:: project diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index bb50465ad3c..4d801d34604 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -84,8 +84,8 @@ It adds these directives: ``dot`` command within the directive. .. versionadded:: 1.5 - All three directives support a ``align`` option to align the graph horizontal. - The values "left", "center", "right" are allowed. + All three directives support a ``align`` option to align the graph + horizontal. The values "left", "center", "right" are allowed. .. versionadded:: 1.6 All three directives support a ``name`` option to set the label to graph. diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst index 2bd9d0e3b32..837c0b35a87 100644 --- a/doc/usage/extensions/ifconfig.rst +++ b/doc/usage/extensions/ifconfig.rst @@ -33,6 +33,6 @@ This extension is quite simple, and features only one directive: def setup(app): app.add_config_value('releaselevel', '', 'env') - The second argument is the default value, the third should always be ``'env'`` - for such values (it selects if Sphinx re-reads the documents if the value - changes). + The second argument is the default value, the third should always be + ``'env'`` for such values (it selects if Sphinx re-reads the documents if the + value changes). diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 8c784e158d2..6f79f8c17e4 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -1197,8 +1197,9 @@ and template arguments for the prefix of qualified names. For example: - ``template\ template\ Wrapper::Outer::Inner`` (:cpp:class:`template\ template\ Wrapper::Outer::Inner`) -Currently the lookup only succeed if the template parameter identifiers are equal -strings. That is, ``template\ Wrapper::Outer`` will not work. +Currently the lookup only succeed if the template parameter identifiers are +equal strings. That is, ``template\ Wrapper::Outer`` will not +work. As a shorthand notation, if a template parameter list is omitted, then the lookup will assume either a primary template or a non-template, diff --git a/utils/doclinter.py b/utils/doclinter.py index 01b043ab88f..52b2fe892b0 100644 --- a/utils/doclinter.py +++ b/utils/doclinter.py @@ -14,7 +14,7 @@ from typing import List -MAX_LINE_LENGTH = 90 +MAX_LINE_LENGTH = 85 LONG_INTERPRETED_TEXT = re.compile(r'^\s*\W*(:(\w+:)+)?`.*`\W*$') CODE_BLOCK_DIRECTIVE = re.compile(r'^(\s*)\.\. code-block::') LEADING_SPACES = re.compile(r'^(\s*)')