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

Merge branch '2.0'

Browse Source
This commit is contained in:
Takeshi KOMIYA
2019-05-29 00:51:25 +09:00
parent f63abac2ca 804d5d804a
commit b9d7239d90
55 changed files with 972 additions and 342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/develop.rst
View File

@@ -46,7 +46,8 @@ This is the current list of contributed extensions in that repository:
- coffeedomain: a domain for (auto)documenting CoffeeScript source code
- context: a builder for ConTeXt
- disqus: embed Disqus comments in documents
- documentedlist: converts a Python list to a table in the generated documentation
- documentedlist: converts a Python list to a table in the generated
documentation
- doxylink: Link to external Doxygen-generated HTML documentation
- domaintools_: A tool for easy domain creation
- email: obfuscate email addresses
@@ -76,7 +77,8 @@ This is the current list of contributed extensions in that repository:
- nicovideo: embed videos from nicovideo
- nwdiag: embed network diagrams by using nwdiag_
- omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed)
- osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension)
- osaka: convert standard Japanese doc to Osaka dialect (this is a joke
extension)
- paverutils: an alternate integration of Sphinx with Paver_
- phpdomain: an extension for PHP support
- plantuml: embed UML diagram by using PlantUML_
@@ -96,7 +98,8 @@ This is the current list of contributed extensions in that repository:
- sword: an extension inserting Bible verses from Sword_
- tikz: draw pictures with the `TikZ/PGF LaTeX package`_
- traclinks: create TracLinks_ to a Trac_ instance from within Sphinx
- versioning: Sphinx extension that allows building versioned docs for self-hosting
- versioning: Sphinx extension that allows building versioned docs for
self-hosting
- whooshindex: whoosh indexer extension
- youtube: embed videos from YouTube_
- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_

6
doc/extdev/appapi.rst
View File

@@ -145,9 +145,9 @@ Sphinx core events
------------------
These events are known to the core. The arguments shown are given to the
registered event handlers. Use :meth:`.Sphinx.connect` in an extension's ``setup``
function (note that ``conf.py`` can also have a ``setup`` function) to connect
handlers to the events. Example:
registered event handlers. Use :meth:`.Sphinx.connect` in an extension's
``setup`` function (note that ``conf.py`` can also have a ``setup`` function) to
connect handlers to the events. Example:
.. code-block:: python

9
doc/extdev/deprecated.rst
View File

@@ -171,6 +171,11 @@ The following is a list of deprecated interfaces.
- 4.0
- N/A
* - ``sphinx.ext.apidoc.makename()``
- 2.1
- 4.0
- ``sphinx.ext.apidoc.module_join()``
* - ``sphinx.ext.autodoc.importer.MockFinder``
- 2.1
- 4.0
@@ -1066,7 +1071,9 @@ The following is a list of deprecated interfaces.
* - ``sphinx.websupport``
- 1.6
- 2.0
- `sphinxcontrib-websupport <https://pypi.org/project/sphinxcontrib-websupport/>`_
- `sphinxcontrib-websupport`_
.. _sphinxcontrib-websupport: https://pypi.org/project/sphinxcontrib-websupport/
* - ``StandaloneHTMLBuilder.css_files``
- 1.6

4
doc/extdev/logging.rst
View File

@@ -56,8 +56,8 @@ Logging API
:meth:`SphinxLoggerAdapter.warning`.
**color**
The color of logs. By default, info and verbose level logs are not colored,
and debug level ones are colored as ``"darkgray"``.
The color of logs. By default, info and verbose level logs are not
colored, and debug level ones are colored as ``"darkgray"``.
.. autofunction:: pending_logging()

4
doc/extdev/markupapi.rst
View File

@@ -138,8 +138,8 @@ Both APIs parse the content into a given node. They are used like this::
.. deprecated:: 1.7
Until Sphinx-1.6, ``sphinx.ext.autodoc.AutodocReporter`` is used for this purpose.
For now, it is replaced by ``switch_source_input()``.
Until Sphinx-1.6, ``sphinx.ext.autodoc.AutodocReporter`` is used for this
purpose. For now, it is replaced by ``switch_source_input()``.
If you don't need the wrapping node, you can use any concrete node type and
return ``node.children`` from the Directive.

6
doc/faq.rst
View File

@@ -37,9 +37,6 @@ How do I...
You'll still need to mark up classes and such, but the headings and code
examples come through cleanly.
... create HTML slides from Sphinx documents?
See the "Hieroglyph" package at https://github.com/nyergler/hieroglyph.
For many more extensions and other contributed stuff, see the sphinx-contrib_
repository.
@@ -83,7 +80,8 @@ GitHub Pages
Sphinx HTML output properly.
MediaWiki
See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by Kevin Dunn.
See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by
Kevin Dunn.
Google Analytics
You can use a custom ``layout.html`` template, like this:

4
doc/intro.rst
View File

@@ -17,10 +17,10 @@ docs have a look at `Epydoc <http://epydoc.sourceforge.net/>`_, which also
understands reST.
For a great "introduction" to writing docs in general -- the whys and hows, see
also `Write the docs <https://write-the-docs.readthedocs.io/>`_, written by Eric
Holscher.
also `Write the docs`_, written by Eric Holscher.
.. _rinohtype: https://github.com/brechtm/rinohtype
.. _Write the docs: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
Conversion from other systems
-----------------------------

3
doc/man/sphinx-apidoc.rst
View File

@@ -4,7 +4,8 @@ sphinx-apidoc
Synopsis
--------
**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*> [*EXCLUDE_PATTERN*, ...]
**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*>
[*EXCLUDE_PATTERN*, ...]
Description
-----------

3
doc/man/sphinx-build.rst
View File

@@ -302,7 +302,8 @@ variables to customize behavior:
.. describe:: SPHINXOPTS
Additional options for :program:`sphinx-build`.
Additional options for :program:`sphinx-build`. These options can
also be set via the shortcut variable **O** (capital 'o').
.. _when-deprecation-warnings-are-displayed:

5
doc/theming.rst
View File

@@ -49,8 +49,9 @@ Python :mod:`ConfigParser` module) and has the following structure:
* The **inherit** setting gives the name of a "base theme", or ``none``. The
base theme will be used to locate missing templates (most themes will not have
to supply most templates if they use ``basic`` as the base theme), its options
will be inherited, and all of its static files will be used as well. If you want
to also inherit the stylesheet, include it via CSS' ``@import`` in your own.
will be inherited, and all of its static files will be used as well. If you
want to also inherit the stylesheet, include it via CSS' ``@import`` in your
own.
* The **stylesheet** setting gives the name of a CSS file which will be
referenced in the HTML header. If you need more than one CSS file, either

2
doc/usage/advanced/websupport/quickstart.rst
View File

@@ -63,7 +63,7 @@ This dict can then be used as context for templates. The goal is to be easy to
integrate with your existing templating system. An example using `Jinja2
<http://jinja.pocoo.org/>`_ is:
.. sourcecode:: html+jinja
.. code-block:: html+jinja
{%- extends "layout.html" %}

2
doc/usage/builders/index.rst
View File

@@ -61,7 +61,7 @@ The builder's "name" must be given to the **-b** command-line option of
.. versionadded:: 1.0
.. module:: sphinx.builders.htmlhelp
.. module:: sphinxcontrib.htmlhelp
.. class:: HTMLHelpBuilder
This builder produces the same output as the standalone HTML builder, but

43
doc/usage/configuration.rst
View File

@@ -296,25 +296,26 @@ General configuration
Sphinx supports following warning types:
* app.add_node
* app.add_directive
* app.add_role
* app.add_generic_role
* app.add_source_parser
* download.not_readable
* image.not_readable
* ref.term
* ref.ref
* ref.numref
* ref.keyword
* ref.option
* ref.citation
* ref.footnote
* ref.doc
* ref.python
* misc.highlighting_failure
* toc.secnum
* epub.unknown_project_files
* ``app.add_node``
* ``app.add_directive``
* ``app.add_role``
* ``app.add_generic_role``
* ``app.add_source_parser``
* ``download.not_readable``
* ``image.not_readable``
* ``ref.term``
* ``ref.ref``
* ``ref.numref``
* ``ref.keyword``
* ``ref.option``
* ``ref.citation``
* ``ref.footnote``
* ``ref.doc``
* ``ref.python``
* ``misc.highlighting_failure``
* ``toc.secnum``
* ``epub.unknown_project_files``
* ``autosectionlabel.*``
You can choose from these types.
@@ -334,6 +335,10 @@ General configuration
Added ``ref.footnote``
.. versionchanged:: 2.1
Added ``autosectionlabel.*``
.. confval:: needs_sphinx
If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will

6
doc/usage/extensions/autodoc.rst
View File

@@ -40,10 +40,8 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your
docstrings to correct reStructuredText before :mod:`autodoc` processes them.
.. _Google:
https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
.. _NumPy:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
.. _NumPy: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Directives

12
doc/usage/extensions/coverage.rst
View File

@@ -22,6 +22,16 @@ should check:
.. confval:: coverage_ignore_classes
.. confval:: coverage_ignore_pyobjects
List of `Python regular expressions`_.
If any of these regular expressions matches any part of the full import path
of a Python object, that Python object is excluded from the documentation
coverage report.
.. versionadded:: 2.1
.. confval:: coverage_c_path
.. confval:: coverage_c_regexes
@@ -40,3 +50,5 @@ should check:
``False`` by default.
.. versionadded:: 1.1
.. _Python regular expressions: https://docs.python.org/library/re

4
doc/usage/extensions/inheritance.rst
View File

@@ -36,8 +36,8 @@ It adds this directive:
with ``lib.``, you can give ``:parts: -1`` to remove that prefix from the
displayed node names.
The directive also supports a ``private-bases`` flag option; if given, private base
classes (those whose name starts with ``_``) will be included.
The directive also supports a ``private-bases`` flag option; if given,
private base classes (those whose name starts with ``_``) will be included.
You can use ``caption`` option to give a caption to the diagram.

13
doc/usage/extensions/todo.rst
View File

@@ -17,8 +17,9 @@ There are two additional directives when using this extension:
``True``.
.. versionadded:: 1.3.2
This directive supports an ``class`` option that determines the class attribute
for HTML output. If not given, the class defaults to ``admonition-todo``.
This directive supports an ``class`` option that determines the class
attribute for HTML output. If not given, the class defaults to
``admonition-todo``.
.. rst:directive:: todolist
@@ -46,8 +47,8 @@ Configuration
.. confval:: todo_link_only
If this is ``True``, :rst:dir:`todolist` produce output without file path and line,
The default is ``False``.
If this is ``True``, :rst:dir:`todolist` produce output without file path and
line, The default is ``False``.
.. versionadded:: 1.4
@@ -57,5 +58,5 @@ autodoc provides the following an additional event:
.. versionadded:: 1.5
Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node``
node.
Emitted when a todo is defined. *node* is the defined
``sphinx.ext.todo.todo_node`` node.

35
doc/usage/restructuredtext/directives.rst
View File

@@ -686,8 +686,8 @@ Glossary
(When the glossary is sorted, the first term determines the sort order.)
If you want to specify "grouping key" for general index entries, you can put a "key"
as "term : key". For example::
If you want to specify "grouping key" for general index entries, you can put
a "key" as "term : key". For example::
.. glossary::
@@ -697,12 +697,12 @@ Glossary
Note that "key" is used for grouping key as is.
The "key" isn't normalized; key "A" and "a" become different groups.
The whole characters in "key" is used instead of a first character; it is used for
"Combining Character Sequence" and "Surrogate Pairs" grouping key.
The whole characters in "key" is used instead of a first character; it is
used for "Combining Character Sequence" and "Surrogate Pairs" grouping key.
In i18n situation, you can specify "localized term : key" even if original text only
have "term" part. In this case, translated "localized term" will be categorized in
"key" group.
In i18n situation, you can specify "localized term : key" even if original
text only have "term" part. In this case, translated "localized term" will be
categorized in "key" group.
.. versionadded:: 0.6
You can now give the glossary directive a ``:sorted:`` flag that will
@@ -958,16 +958,16 @@ this reason, the following directive exists:
.. warning::
Tables with more than 30 rows are rendered using ``longtable``, not
``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers
do not work for these tables.
``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ...
specifiers do not work for these tables.
Tables that contain list-like elements such as object descriptions,
blockquotes or any kind of lists cannot be set out of the box with
``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or
``longtable``) environment if you don't give a ``tabularcolumns`` directive.
If you do, the table will be set with ``tabulary`` but you must use the
``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described
below) for the columns containing these elements.
``tabulary``. They are therefore set with the standard LaTeX ``tabular``
(or ``longtable``) environment if you don't give a ``tabularcolumns``
directive. If you do, the table will be set with ``tabulary`` but you
must use the ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y``
specifiers described below) for the columns containing these elements.
Literal blocks do not work with ``tabulary`` at all, so tables containing
a literal block are always set with ``tabular``. The verbatim environment
@@ -996,10 +996,11 @@ this reason, the following directive exists:
.. versionchanged:: 1.6
Merged cells from complex grid tables (either multi-row, multi-column, or
both) now allow blockquotes, lists, literal blocks, ... as do regular cells.
both) now allow blockquotes, lists, literal blocks, ... as do regular
cells.
Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}``
and tabulary's columns.
Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``,
``Y{f}`` and tabulary's columns.
.. note::

114
doc/usage/restructuredtext/domains.rst
View File

@@ -128,17 +128,28 @@ declarations:
This directive will also cause an entry in the global module index.
The ``platform`` option, if present, is a comma-separated list of the
platforms on which the module is available (if it is available on all
platforms, the option should be omitted). The keys are short identifiers;
examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is
important to use a key which has already been used when applicable.
.. rubric:: options
The ``synopsis`` option should consist of one sentence describing the
module's purpose -- it is currently only used in the Global Module Index.
.. rst:directive:option:: platform: platforms
:type: comma separated list
The ``deprecated`` option can be given (with no value) to mark a module as
deprecated; it will be designated as such in various locations then.
Indicate platforms which the module is available (if it is available on
all platforms, the option should be omitted). The keys are short
identifiers; examples that are in use include "IRIX", "Mac", "Windows"
and "Unix". It is important to use a key which has already been used when
applicable.
.. rst:directive:option:: synopsis: purpose
:type: text
Consist of one sentence describing the module's purpose -- it is currently
only used in the Global Module Index.
.. rst:directive:option:: deprecated
:type: no argument
Mark a module as deprecated; it will be designated as such in various
locations then.
.. rst:directive:: .. py:currentmodule:: name
@@ -169,12 +180,14 @@ The following directives are provided for module and class contents:
This information can (in any ``py`` directive) optionally be given in a
structured form, see :ref:`info-field-lists`.
The ``async`` option can be given (with no value) to indicate the function is
an async method.
.. rubric:: options
.. versionchanged:: 2.1
.. rst:directive:option:: async
:type: no value
``:async:`` option added.
Indicate the function is an async function.
.. versionadded:: 2.1
.. rst:directive:: .. py:data:: name
@@ -223,19 +236,43 @@ The following directives are provided for module and class contents:
described for ``function``. See also :ref:`signatures` and
:ref:`info-field-lists`.
The ``async`` option can be given (with no value) to indicate the method is
an async method.
.. rubric:: options
The ``classmethod`` option and ``staticmethod`` option can be given (with
no value) to indicate the method is a class method (or a static method).
.. rst:directive:option:: abstractmethod
:type: no value
The ``property`` option can be given (with no value) to indicate the method
is a property.
Indicate the method is an abstract method.
.. versionchanged:: 2.1
.. versionadded:: 2.1
.. rst:directive:option:: async
:type: no value
Indicate the method is an async method.
.. versionadded:: 2.1
.. rst:directive:option:: classmethod
:type: no value
Indicate the method is a class method.
.. versionadded:: 2.1
.. rst:directive:option:: property
:type: no value
Indicate the method is a property.
.. versionadded:: 2.1
.. rst:directive:option:: staticmethod
:type: no value
Indicate the method is a static method.
.. versionadded:: 2.1
``:async:``, ``:classmethod:``, ``:property:`` and ``:staticmethod:``
options added.
.. rst:directive:: .. py:staticmethod:: name(parameters)
@@ -720,7 +757,8 @@ visibility statement (``public``, ``private`` or ``protected``).
.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
A scoped enum with non-default visibility, and with a specified underlying type.
A scoped enum with non-default visibility, and with a specified
underlying type.
.. rst:directive:: .. cpp:enumerator:: name
.. cpp:enumerator:: name = constant
@@ -760,7 +798,8 @@ visibility statement (``public``, ``private`` or ``protected``).
**Valid Expressions**
- :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
- :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.
- :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
:cpp:expr:`r` is incrementable.
This will render as follows:
@@ -799,11 +838,12 @@ Anonymous Entities
~~~~~~~~~~~~~~~~~~
C++ supports anonymous namespaces, classes, enums, and unions.
For the sake of documentation they must be given some name that starts with ``@``,
e.g., ``@42`` or ``@data``.
For the sake of documentation they must be given some name that starts with
``@``, e.g., ``@42`` or ``@data``.
These names can also be used in cross-references and (type) expressions,
though nested symbols will be found even when omitted.
The ``@...`` name will always be rendered as **[anonymous]** (possibly as a link).
The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
link).
Example::
@@ -835,8 +875,8 @@ Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
Aliasing Declarations
~~~~~~~~~~~~~~~~~~~~~
Sometimes it may be helpful list declarations elsewhere than their main documentation,
e.g., when creating a synopsis of a class interface.
Sometimes it may be helpful list declarations elsewhere than their main
documentation, e.g., when creating a synopsis of a class interface.
The following directive can be used for this purpose.
.. rst:directive:: .. cpp:alias:: name or function signature
@@ -1079,7 +1119,8 @@ These roles link to the given declaration types:
be properly qualified relative to the position of the link.
.. versionadded:: 2.0
The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` role.
The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class`
role.
.. admonition:: Note on References with Templates Parameters/Arguments
@@ -1126,7 +1167,8 @@ References using the :rst:role:`cpp:func` role:
- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
- Specific overload: ``void C::f(double) const``, :cpp:func:`void C::f(double) const`
- Specific overload: ``void C::f(double) const``,
:cpp:func:`void C::f(double) const`
Note that the :confval:`add_function_parentheses` configuration variable
does not influence specific overload references.
@@ -1155,8 +1197,8 @@ and template arguments for the prefix of qualified names. For example:
- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
(:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`)
Currently the lookup only succeed if the template parameter identifiers are equal strings.
That is, ``template\<typename UOuter> Wrapper::Outer`` will not work.
Currently the lookup only succeed if the template parameter identifiers are equal
strings. That is, ``template\<typename UOuter> 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,
@@ -1447,8 +1489,8 @@ The reStructuredText domain (name **rst**) provides the following directives:
.. rubric:: options
.. rst:directive:option:: type
:type: description for the option of directive
.. rst:directive:option:: type: description of argument
:type: text
Describe the type of option value.
@@ -1459,7 +1501,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
.. rst:directive:option:: maxdepth
:type: integer or no value
.. versionadded:: 2.1
.. versionadded:: 2.1
.. rst:directive:: .. rst:role:: name