diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/advanced/intl.rst | 4 | ||||
| -rw-r--r-- | doc/usage/configuration.rst | 29 | ||||
| -rw-r--r-- | doc/usage/extensions/autodoc.rst | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/math.rst | 12 | ||||
| -rw-r--r-- | doc/usage/installation.rst | 4 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/domains.rst | 42 | ||||
| -rw-r--r-- | doc/usage/theming.rst | 39 |
8 files changed, 83 insertions, 51 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/configuration.rst b/doc/usage/configuration.rst index 49e41b078..ba5c15bb3 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -478,11 +478,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 @@ -833,13 +832,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 @@ -1461,8 +1463,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 @@ -1939,8 +1940,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. @@ -1970,6 +1971,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 @@ -2289,10 +2294,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: diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 5222592ab..ed85c941e 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -586,7 +586,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/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..0ea54b220 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. @@ -183,7 +183,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/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/domains.rst b/doc/usage/restructuredtext/domains.rst index f3754ab7c..b659ba8f3 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,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:method:: name(parameters) Describes an object method. The parameters should not include the ``self`` @@ -307,6 +339,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 @@ -1823,7 +1863,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/ |