diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/advanced/intl.rst | 4 | ||||
| -rw-r--r-- | doc/usage/builders/index.rst | 23 | ||||
| -rw-r--r-- | doc/usage/configuration.rst | 88 | ||||
| -rw-r--r-- | doc/usage/extensions/autodoc.rst | 162 | ||||
| -rw-r--r-- | doc/usage/extensions/autosummary.rst | 18 | ||||
| -rw-r--r-- | doc/usage/extensions/math.rst | 12 | ||||
| -rw-r--r-- | doc/usage/installation.rst | 29 | ||||
| -rw-r--r-- | doc/usage/quickstart.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst | 19 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/domains.rst | 64 | ||||
| -rw-r--r-- | doc/usage/theming.rst | 39 |
12 files changed, 316 insertions, 146 deletions
diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index 67d5e10e5..03b77fb6b 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -306,7 +306,7 @@ Contributing to Sphinx reference translation The recommended way for new contributors to translate Sphinx reference is to join the translation team on Transifex. -There is `sphinx translation page`_ for Sphinx (master) documentation. +There is a `sphinx translation page`_ for Sphinx (master) documentation. 1. Login to transifex_ service. 2. Go to `sphinx translation page`_. @@ -314,6 +314,8 @@ There is `sphinx translation page`_ for Sphinx (master) documentation. 4. Wait acceptance by transifex sphinx translation maintainers. 5. (After acceptance) Translate on transifex. +Detail is here: https://docs.transifex.com/getting-started-1/translators + .. rubric:: Footnotes .. [1] See the `GNU gettext utilities diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index c45a8062f..74853fee9 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -179,6 +179,7 @@ The builder's "name" must be given to the **-b** command-line option of * ``texlive-latex-recommended`` * ``texlive-fonts-recommended`` + * ``tex-gyre`` (if :confval:`latex_engine` is ``'pdflatex'``) * ``texlive-latex-extra`` * ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X for functioning of ``make latexpdf``) @@ -186,17 +187,14 @@ The builder's "name" must be given to the **-b** command-line option of Additional packages are needed in some circumstances (see the discussion of the ``'fontpkg'`` key of :confval:`latex_elements` for more information): - * to support occasional Cyrillic letters or words, and a fortiori if - :confval:`language` is set to a Cyrillic language, the package - ``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``, - also ``cm-super`` or ``cm-super-minimal``, - * to support occasional Greek letters or words (in text, not in - :rst:dir:`math` directive contents), ``texlive-lang-greek`` is required, - and, with unmodified ``'fontpkg'``, also ``cm-super`` or - ``cm-super-minimal``, - * for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`), - ``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged - ``'fontpkg'``, ``fonts-freefont-otf``. + * ``texlive-lang-cyrillic`` for Cyrillic (even individual letters), and, + ``cm-super`` or ``cm-super-minimal`` (if default fonts), + * ``texlive-lang-greek`` for Greek (even individual letters), and, + ``cm-super`` or ``cm-super-minimal`` (if default fonts), + * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``, + * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``, + * ``fonts-freefont-otf`` if :confval:`latex_engine` is ``'xelatex'`` + or ``'lualatex'``. The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution is based on a TeXLive 2015 snapshot dated March 2016. @@ -207,6 +205,9 @@ The builder's "name" must be given to the **-b** command-line option of .. versionchanged:: 2.0 Formerly, testing had been done on Ubuntu trusty (TeXLive 2013). + .. versionchanged:: 4.0.0 + TeX Gyre fonts dependency for the default LaTeX font configuration. + .. note:: Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index c2250eb7d..989ce8737 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -183,11 +183,20 @@ General configuration .. confval:: master_doc - The document name of the "master" document, that is, the document that + Same as :confval:`root_doc`. + + .. versionchanged:: 4.0 + Renamed ``master_doc`` to ``master_doc``. + +.. confval:: root_doc + + The document name of the "root" document, that is, the document that contains the root :rst:dir:`toctree` directive. Default is ``'index'``. .. versionchanged:: 2.0 The default is changed to ``'index'`` from ``'contents'``. + .. versionchanged:: 4.0 + Renamed ``master_doc`` from ``master_doc``. .. confval:: exclude_patterns @@ -479,11 +488,10 @@ General configuration .. confval:: smartquotes_action - This string, for use with Docutils ``0.14`` or later, customizes the Smart - Quotes transform. See the file :file:`smartquotes.py` at the `Docutils - repository`__ for details. The default ``'qDe'`` educates normal **q**\ - uote characters ``"``, ``'``, em- and en-**D**\ ashes ``---``, ``--``, and - **e**\ llipses ``...``. + This string customizes the Smart Quotes transform. See the file + :file:`smartquotes.py` at the `Docutils repository`__ for details. The + default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``, + em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``. .. versionadded:: 1.6.6 @@ -834,13 +842,16 @@ documentation on :ref:`intl` for details. :literal-block: literal blocks (``::`` annotation and ``code-block`` directive) :doctest-block: doctest block :raw: raw content - :image: image/figure uri and alt + :image: image/figure uri For example: ``gettext_additional_targets = ['literal-block', 'image']``. The default is ``[]``. .. versionadded:: 1.3 + .. versionchanged:: 4.0 + + The alt text for image is translated by default. .. confval:: figure_language_filename @@ -970,10 +981,15 @@ that use Sphinx's HTMLWriter class. The style of line numbers for code-blocks. - * ``'table'`` -- display line numbers using ``<table>`` tag (default) - * ``'inline'`` -- display line numbers using ``<span>`` tag + * ``'table'`` -- display line numbers using ``<table>`` tag + * ``'inline'`` -- display line numbers using ``<span>`` tag (default) .. versionadded:: 3.2 + .. versionchanged:: 4.0 + + It defaults to ``'inline'``. + + .. deprecated:: 4.0 .. confval:: html_context @@ -986,26 +1002,32 @@ that use Sphinx's HTMLWriter class. .. confval:: html_logo If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the logo of the docs. It is placed - at the top of the sidebar; its width should therefore not exceed 200 pixels. - Default: ``None``. + :term:`configuration directory`) that is the logo of the docs, or URL that + points an image file for the logo. It is placed at the top of the sidebar; + its width should therefore not exceed 200 pixels. Default: ``None``. .. versionadded:: 0.4.1 The image file will be copied to the ``_static`` directory of the output HTML, but only if the file does not already exist there. + .. versionchanged:: 4.0 + Also accepts the URL for the logo file. + .. confval:: html_favicon If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the favicon of the docs. Modern - browsers use this as the icon for tabs, windows and bookmarks. It should - be a Windows-style icon file (``.ico``), which is 16x16 or 32x32 - pixels large. Default: ``None``. + :term:`configuration directory`) that is the favicon of the docs, or URL that + points an image file for the favicon. Modern browsers use this as the icon + for tabs, windows and bookmarks. It should be a Windows-style icon file + (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``. .. versionadded:: 0.4 The image file will be copied to the ``_static`` directory of the output HTML, but only if the file does not already exist there. + .. versionchanged:: 4.0 + Also accepts the URL for the favicon. + .. confval:: html_css_files A list of CSS files. The entry must be a *filename* string or a tuple @@ -1479,8 +1501,7 @@ that use Sphinx's HTMLWriter class. .. confval:: html_experimental_html5_writer - Output is processed with HTML5 writer. This feature needs docutils 0.13 or - newer. Default is ``False``. + Output is processed with HTML5 writer. Default is ``False``. .. versionadded:: 1.6 @@ -1957,8 +1978,8 @@ These options influence LaTeX output. * ``'pdflatex'`` -- PDFLaTeX (default) * ``'xelatex'`` -- XeLaTeX * ``'lualatex'`` -- LuaLaTeX - * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``) - * ``'uplatex'`` -- upLaTeX (experimental) + * ``'platex'`` -- pLaTeX + * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``) ``'pdflatex'``\ 's support for Unicode characters is limited. @@ -1988,6 +2009,10 @@ These options influence LaTeX output. Add ``uplatex`` support. + .. versionchanged:: 4.0 + + ``uplatex`` becomes the default setting of Japanese documents. + Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`, LaTeX requires some extra configuration to support Unicode literals in :rst:dir:`math`: the only comprehensive solution (as far as we know) is to @@ -2007,8 +2032,8 @@ These options influence LaTeX output. *startdocname* String that specifies the :term:`document name` of the LaTeX file's master document. All documents referenced by the *startdoc* document in TOC trees - will be included in the LaTeX file. (If you want to use the default master - document for your LaTeX build, provide your :confval:`master_doc` here.) + will be included in the LaTeX file. (If you want to use the default root + document for your LaTeX build, provide your :confval:`root_doc` here.) *targetname* File name of the LaTeX file in the output directory. @@ -2277,7 +2302,7 @@ These options influence manual page output. String that specifies the :term:`document name` of the manual page's master document. All documents referenced by the *startdoc* document in TOC trees will be included in the manual file. (If you want to use the default - master document for your manual pages build, use your :confval:`master_doc` + root document for your manual pages build, use your :confval:`root_doc` here.) *name* @@ -2307,10 +2332,12 @@ These options influence manual page output. .. confval:: man_make_section_directory - If true, make a section directory on build man page. Default is False. + If true, make a section directory on build man page. Default is True. .. versionadded:: 3.3 + .. versionchanged:: 4.0 + The default is changed to ``False`` from ``True``. .. _texinfo-options: @@ -2331,7 +2358,7 @@ These options influence Texinfo output. master document. All documents referenced by the *startdoc* document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your - :confval:`master_doc` here.) + :confval:`root_doc` here.) *targetname* File name (no extension) of the Texinfo file in the output directory. @@ -2687,6 +2714,17 @@ Options for the C++ domain .. versionadded:: 1.5 +Options for the Python domain +----------------------------- + +.. confval:: python_use_unqualified_type_names + + If true, suppress the module name of the python reference if it can be + resolved. The default is ``False``. + + .. versionadded:: 4.0 + + .. note:: This configuration is still in experimental Example of configuration file ============================= diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index a07042781..1bfa8086c 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -89,33 +89,96 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, Boil the noodle *time* minutes. - **Options and advanced usage** + .. rubric:: Options + + .. rst:directive:option:: members + :type: no value or comma separated list + + If set, autodoc will generate document for the members of the target + module, class or exception. - * If you want to automatically document members, there's a ``members`` - option:: + For example:: .. automodule:: noodle :members: - will document all module members (recursively), and :: + will document all module members (recursively), and :: .. autoclass:: Noodle :members: - will document all non-private member functions and properties (that is, - those whose name doesn't start with ``_``). + will document all class member methods and properties. - For modules, ``__all__`` will be respected when looking for members unless - you give the ``ignore-module-all`` flag option. Without - ``ignore-module-all``, the order of the members will also be the order in - ``__all__``. + By default, autodoc will not generate document for the members that are + private, not having docstrings, inherited from super class, or special + members. - You can also give an explicit list of members; only these will then be - documented:: + For modules, ``__all__`` will be respected when looking for members unless + you give the ``ignore-module-all`` flag option. Without + ``ignore-module-all``, the order of the members will also be the order in + ``__all__``. + + You can also give an explicit list of members; only these will then be + documented:: .. autoclass:: Noodle :members: eat, slurp + .. rst:directive:option:: undoc-members + :type: no value + + If set, autodoc will also generate document for the members not having + docstrings:: + + .. automodule:: noodle + :members: + :undoc-members: + + .. rst:directive:option:: private-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the private members + (that is, those named like ``_private`` or ``__private``):: + + .. automodule:: noodle + :members: + :private-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. automodule:: noodle + :members: + :private-members: _spicy, _garlickly + + .. versionadded:: 1.1 + .. versionchanged:: 3.2 + The option can now take arguments. + + .. rst:directive:option:: special-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the special members + (that is, those named like ``__special__``):: + + .. autoclass:: my.Class + :members: + :special-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. autoclass:: my.Class + :members: + :special-members: __init__, __name__ + + .. versionadded:: 1.1 + + .. versionchanged:: 1.2 + The option can now take arguments + + **Options and advanced usage** + * If you want to make the ``members`` option (or other options described below) the default, see :confval:`autodoc_default_options`. @@ -139,31 +202,6 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionchanged:: 3.5 The default options can be overridden or extended temporarily. - * Members without docstrings will be left out, unless you give the - ``undoc-members`` flag option:: - - .. automodule:: noodle - :members: - :undoc-members: - - * "Private" members (that is, those named like ``_private`` or ``__private``) - will be included if the ``private-members`` flag option is given:: - - .. automodule:: noodle - :members: - :private-members: - - It can also take an explicit list of member names to be documented as - arguments:: - - .. automodule:: noodle - :members: - :private-members: _spicy, _garlickly - - .. versionadded:: 1.1 - .. versionchanged:: 3.2 - The option can now take arguments. - * autodoc considers a member private if its docstring contains ``:meta private:`` in its :ref:`info-field-lists`. For example: @@ -203,21 +241,6 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionadded:: 3.5 - * Python "special" members (that is, those named like ``__special__``) will - be included if the ``special-members`` flag option is given:: - - .. autoclass:: my.Class - :members: - :private-members: - :special-members: - - would document both "private" and "special" members of the class. - - .. versionadded:: 1.1 - - .. versionchanged:: 1.2 - The option can now take arguments, i.e. the special members to document. - * For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the ``inherited-members`` option, in addition to ``members``:: @@ -506,15 +529,19 @@ There are also config values that you can set: looks like a signature, use the line as the signature and remove it from the docstring content. - If the signature line ends with backslash, autodoc considers the function has - multiple signatures and look at the next line of the docstring. It is useful - for overloaded function. + autodoc will continue to look for multiple signature lines, + stopping at the first line that does not look like a signature. + This is useful for declaring overloaded function signatures. .. versionadded:: 1.1 .. versionchanged:: 3.1 Support overloaded signatures + .. versionchanged:: 4.0 + + Overloaded signatures do not need to be separated by a backslash + .. confval:: autodoc_mock_imports This value contains a list of modules to be mocked up. This is useful when @@ -548,6 +575,19 @@ There are also config values that you can set: New option ``'description'`` is added. +.. confval:: autodoc_typehints_description_target + + This value controls whether the types of undocumented parameters and return + values are documented when ``autodoc_typehints`` is set to ``description``. + + The default value is ``"all"``, meaning that types are documented for all + parameters and return values, whether they are documented or not. + + When set to ``"documented"``, types will only be documented for a parameter + or a return value that is already documented by the docstring. + + .. versionadded:: 4.0 + .. confval:: autodoc_type_aliases A dictionary for users defined `type aliases`__ that maps a type name to the @@ -586,6 +626,16 @@ There are also config values that you can set: .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases .. versionadded:: 3.3 +.. confval:: autodoc_preserve_defaults + + If True, the default argument values of functions will be not evaluated on + generating document. It preserves them as is in the source code. + + .. versionadded:: 4.0 + + Added as an experimental feature. This will be integrated into autodoc core + in the future. + .. confval:: autodoc_warningiserror This value controls the behavior of :option:`sphinx-build -W` during @@ -597,7 +647,7 @@ There are also config values that you can set: This value controls the docstrings inheritance. If set to True the docstring for classes or methods, if not explicitly set, - is inherited form parents. + is inherited from parents. The default is ``True``. diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 03ea7548e..28f207de7 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -19,11 +19,13 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: that contain links to the documented items, and short summary blurbs extracted from their docstrings. -2. Optionally, the convenience script :program:`sphinx-autogen` or the new - :confval:`autosummary_generate` config value can be used to generate short - "stub" files for the entries listed in the :rst:dir:`autosummary` directives. - These files by default contain only the corresponding - :mod:`sphinx.ext.autodoc` directive, but can be customized with templates. +2. A :rst:dir:`autosummary` directive also generates short "stub" files for the + entries listed in its content. These files by default contain only the + corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with + templates. + + The :program:`sphinx-autogen` script is also able to generate "stub" files + from command line. .. rst:directive:: autosummary @@ -161,7 +163,7 @@ also use these config values: .. confval:: autosummary_generate Boolean indicating whether to scan all found documents for autosummary - directives, and to generate stub pages for each. It is disabled by default. + directives, and to generate stub pages for each. It is enabled by default. Can also be a list of documents for which stub pages should be generated. @@ -173,6 +175,10 @@ also use these config values: Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc` does. + .. versionchanged:: 4.0 + + Enabled by default. + .. confval:: autosummary_generate_overwrite If true, autosummary overwrites existing files by generated stub pages. diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 780e57ee2..655364767 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -140,6 +140,12 @@ are built: .. module:: sphinx.ext.mathjax :synopsis: Render math using JavaScript via MathJax. +.. warning:: + Version 4.0 changes the version of MathJax used to version 3. You may need to + override ``mathjax_path`` to + ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML`` + or update your configuration options for version 3. + .. versionadded:: 1.1 This extension puts math as-is into the HTML files. The JavaScript package @@ -161,14 +167,14 @@ Sphinx but is set to automatically include it from a third-party site. MathJax. The default is the ``https://`` URL that loads the JS files from the - `cdnjs`__ Content Delivery Network. See the `MathJax Getting Started + `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started page`__ for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path. - __ https://cdnjs.com + __ https://www.jsdelivr.com/ - __ https://docs.mathjax.org/en/latest/start.html + __ https://www.mathjax.org/#gettingstarted The path can be absolute or relative; if it is relative, it is relative to the ``_static`` directory of the built docs. diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 46ef6a51e..f0384ea9d 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -12,7 +12,7 @@ Installing Sphinx Overview -------- -Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the +Sphinx is written in `Python`__ and supports Python 3.6+. It builds upon the shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__, which are installed when Sphinx is installed. @@ -107,7 +107,30 @@ Anaconda Windows ------- -.. todo:: Could we start packaging this? +Sphinx can be install using `Chocolatey`__ or +:ref:`installed manually <windows-other-method>`. + +__ https://chocolatey.org/ + +Chocolatey +~~~~~~~~~~ + +:: + + $ choco install sphinx + +You would need to `install Chocolatey +<https://chocolatey.org/install/>`_ +before running this. + +For more information, refer to the `chocolatey page`__. + +__ https://chocolatey.org/packages/sphinx/ + +.. _windows-other-method: + +Other Methods +~~~~~~~~~~~~~ Most Windows users do not have Python installed by default, so we begin with the installation of Python itself. To check if you already have Python @@ -183,7 +206,7 @@ Please choose one for your purpose. When using docker images, please use ``docker run`` command to invoke sphinx commands. For example, you can use following command to create a Sphinx project:: - $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart + $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart And you can following command this to build HTML document:: diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 1d7e540a6..3cd6ac993 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -13,7 +13,7 @@ Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx's power comes from the richness of its default plain-text markup format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with -it's :doc:`significant extensibility capabilities </development/index>`. +its :doc:`significant extensibility capabilities </development/index>`. The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you're done here, you can check out the diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 8f596ed9a..03b690f44 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -288,7 +288,7 @@ Roles ----- A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline -piece of explicit markup. It signifies that that the enclosed text should be +piece of explicit markup. It signifies that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is ``:rolename:`content```. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index e8b88c21b..995804e37 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -197,9 +197,9 @@ tables of contents. The ``toctree`` directive is the central element. <metadata>` to let a document be built, but notify Sphinx that it is not reachable via a toctree. - The "master document" (selected by :confval:`master_doc`) is the "root" of - the TOC tree hierarchy. It can be used as the documentation's main page, or - as a "full table of contents" if you don't give a ``maxdepth`` option. + The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC + tree hierarchy. It can be used as the documentation's main page, or as a + "full table of contents" if you don't give a ``maxdepth`` option. .. versionchanged:: 0.3 Added "globbing" option. @@ -404,10 +404,15 @@ Showing code examples single: sourcecode There are multiple ways to show syntax-highlighted literal code blocks in -Sphinx: using :ref:`reST doctest blocks <rst-doctest-blocks>`; using :ref:`reST -literal blocks <rst-literal-blocks>`, optionally in combination with the -:rst:dir:`highlight` directive; using the :rst:dir:`code-block` directive; and -using the :rst:dir:`literalinclude` directive. Doctest blocks can only be used +Sphinx: + +* using :ref:`reST doctest blocks <rst-doctest-blocks>`; +* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in + combination with the :rst:dir:`highlight` directive; +* using the :rst:dir:`code-block` directive; +* and using the :rst:dir:`literalinclude` directive. + +Doctest blocks can only be used to show interactive Python sessions, while the remaining three can be used for other languages. Of these three, literal blocks are useful when an entire document, or at least large sections of it, use code blocks with the same diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 53e1fc5d3..65a32b6c8 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -202,6 +202,14 @@ The following directives are provided for module and class contents: .. versionadded:: 2.1 + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + .. rst:directive:: .. py:data:: name Describes global data in a module, including both variables and values used @@ -220,6 +228,14 @@ The following directives are provided for module and class contents: .. versionadded:: 2.4 + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + .. rst:directive:: .. py:exception:: name Describes an exception class. The signature can, but need not include @@ -259,6 +275,14 @@ The following directives are provided for module and class contents: .. rubric:: options + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + .. rst:directive:option:: final :type: no value @@ -284,6 +308,30 @@ The following directives are provided for module and class contents: .. versionadded:: 2.4 + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + +.. rst:directive:: .. py:property:: name + + Describes an object property. + + .. versionadded:: 4.0 + + .. rubric:: options + + .. rst:directive:option:: abstractmethod + :type: no value + + Indicate the property is abstract. + + .. rst:directive:option:: type: type of the property + :type: text + .. rst:directive:: .. py:method:: name(parameters) Describes an object method. The parameters should not include the ``self`` @@ -307,6 +355,14 @@ The following directives are provided for module and class contents: .. versionadded:: 2.1 + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + .. rst:directive:option:: classmethod :type: no value @@ -328,6 +384,10 @@ The following directives are provided for module and class contents: .. versionadded:: 2.1 + .. deprecated:: 4.0 + + Use :rst:dir:`py:property` instead. + .. rst:directive:option:: staticmethod :type: no value @@ -544,6 +604,8 @@ a matching identifier is found: Reference a data attribute of an object. + .. note:: The role is also able to refer to property. + .. rst:role:: py:exc Reference an exception. A dotted name may be used. @@ -1848,7 +1910,7 @@ currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_ domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_, Jinja_, Operation_, and Scala_. -.. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/ +.. _sphinx-contrib: https://github.com/sphinx-contrib .. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/ .. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/ diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index fb06e8741..fc135a095 100644 --- a/doc/usage/theming.rst +++ b/doc/usage/theming.rst @@ -334,38 +334,15 @@ These themes are: Third Party Themes ~~~~~~~~~~~~~~~~~~ -.. cssclass:: longtable - -+--------------------+--------------------+ -| **Theme overview** | | -+--------------------+--------------------+ -| |sphinx_rtd_theme| | | -| | | -| *sphinx_rtd_theme* | | -+--------------------+--------------------+ - -.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png - -There are many third-party themes available. Some of these are general use, -while others are specific to an individual project. A section of third-party -themes is listed below. Many more can be found on PyPI__, GitHub__, GitLab__ and -sphinx-themes.org__. - -.. cssclass:: clear - -**sphinx_rtd_theme** - `Read the Docs Sphinx Theme`_. - This is a mobile-friendly sphinx theme that was made for readthedocs.org. - View a working demo over on readthedocs.org. You can get install and options - information at `Read the Docs Sphinx Theme`_ page. - - .. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/ - - .. versionchanged:: 1.4 - **sphinx_rtd_theme** has become optional. +There are many third-party themes available for Sphinx. Some of these are for +general use, while others are specific to an individual project. +sphinx-themes.org__ is a gallery that showcases various themes for Sphinx, +with demo documentation rendered under each theme. Themes can also be found +on PyPI__ (using the classifier ``Framework :: Sphinx :: Theme``), GitHub__ +and GitLab__. +.. __: https://sphinx-themes.org/ .. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme -.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type= +.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme .. __: https://gitlab.com/explore?name=sphinx+theme -.. __: https://sphinx-themes.org/ |