diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:25:40 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:25:40 +0000 |
| commit | cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch) | |
| tree | 18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage | |
| parent | Initial commit. (diff) | |
| download | sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip | |
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage')
42 files changed, 14925 insertions, 0 deletions
diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst new file mode 100644 index 0000000..ae6e7dc --- /dev/null +++ b/doc/usage/advanced/intl.rst @@ -0,0 +1,372 @@ +.. _intl: + +Internationalization +==================== + +.. versionadded:: 1.1 + +Complementary to translations provided for Sphinx-generated messages such as +navigation bars, Sphinx provides mechanisms facilitating the translation of +*documents*. See the :ref:`intl-options` for details on configuration. + +.. figure:: /_static/translation.* + :width: 100% + + Workflow visualization of translations in Sphinx. (The figure is created by + `plantuml <https://plantuml.com>`_.) + +.. contents:: + :local: + +Sphinx internationalization details +----------------------------------- + +**gettext** [1]_ is an established standard for internationalization and +localization. It naively maps messages in a program to a translated string. +Sphinx uses these facilities to translate whole documents. + +Initially project maintainers have to collect all translatable strings (also +referred to as *messages*) to make them known to translators. Sphinx extracts +these through invocation of ``sphinx-build -b gettext``. + +Every single element in the doctree will end up in a single message which +results in lists being equally split into different chunks while large +paragraphs will remain as coarsely-grained as they were in the original +document. This grants seamless document updates while still providing a little +bit of context for translators in free-text passages. It is the maintainer's +task to split up paragraphs which are too large as there is no sane automated +way to do that. + +After Sphinx successfully ran the +:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a +collection of ``.pot`` files in your output directory. These are **catalog +templates** and contain messages in your original language *only*. + +They can be delivered to translators which will transform them to ``.po`` files +--- so called **message catalogs** --- containing a mapping from the original +messages to foreign-language strings. + +*gettext* compiles them into a binary format known as **binary catalogs** +through :program:`msgfmt` for efficiency reasons. If you make these files +discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx +will pick them up automatically. + +An example: you have a document ``usage.rst`` in your Sphinx project. The +*gettext* builder will put its messages into ``usage.pot``. Imagine you have +Spanish translations [2]_ stored in ``usage.po`` --- for your builds to +be translated you need to follow these instructions: + +* Compile your message catalog to a locale directory, say ``locale``, so it + ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory + (where ``es`` is the language code for Spanish.) :: + + msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo" + +* Set :confval:`locale_dirs` to ``["locale/"]``. +* Set :confval:`language` to ``es`` (also possible via + :option:`-D <sphinx-build -D>`). +* Run your desired build. + + +In order to protect against mistakes, a warning is emitted if +cross-references in the translated paragraph do not match those from the +original. This can be turned off globally using the +:confval:`suppress_warnings` configuration variable. Alternatively, to +turn it off for one message only, end the message with ``#noqa`` like +this:: + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse + risus tortor, luctus id ultrices at. #noqa + +(Write ``\#noqa`` in case you want to have "#noqa" literally in the +text. This does not apply to code blocks, where ``#noqa`` is ignored +because code blocks do not contain references anyway.) + +.. versionadded:: 4.5 + The ``#noqa`` mechanism. + + +Translating with sphinx-intl +---------------------------- + +Quick guide +~~~~~~~~~~~ + +`sphinx-intl`_ is a useful tool to work with Sphinx translation flow. This +section describe an easy way to translate with *sphinx-intl*. + +#. Install `sphinx-intl`_. + + .. code-block:: console + + $ pip install sphinx-intl + +#. Add configurations to ``conf.py``. + + :: + + locale_dirs = ['locale/'] # path is example but recommended. + gettext_compact = False # optional. + + This case-study assumes that BUILDDIR is set to ``_build``, + :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact` + is set to ``False`` (the Sphinx document is already configured as such). + +#. Extract translatable messages into pot files. + + .. code-block:: console + + $ make gettext + + The generated pot files will be placed in the ``_build/gettext`` directory. + +#. Generate po files. + + We'll use the pot files generated in the above step. + + .. code-block:: console + + $ sphinx-intl update -p _build/gettext -l de -l ja + + Once completed, the generated po files will be placed in the below + directories: + + * ``./locale/de/LC_MESSAGES/`` + * ``./locale/ja/LC_MESSAGES/`` + +#. Translate po files. + + As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES`` + directory. An example of one such file, from Sphinx, ``builders.po``, is + given below. + + .. code-block:: po + + # a5600c3d2e3d48fc8c261ea0284db79b + #: ../../builders.rst:4 + msgid "Available builders" + msgstr "<FILL HERE BY TARGET LANGUAGE>" + + Another case, msgid is multi-line text and contains reStructuredText syntax: + + .. code-block:: po + + # 302558364e1d41c69b3277277e34b184 + #: ../../builders.rst:9 + msgid "" + "These are the built-in Sphinx builders. More builders can be added by " + ":ref:`extensions <extensions>`." + msgstr "" + "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE " + "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE." + + Please be careful not to break reST notation. Most po-editors will help you + with that. + +#. Build translated document. + + You need a :confval:`language` parameter in ``conf.py`` or you may also + specify the parameter on the command line. + + For BSD/GNU make, run: + + .. code-block:: console + + $ make -e SPHINXOPTS="-D language='de'" html + + For Windows :command:`cmd.exe`, run: + + .. code-block:: console + + > set SPHINXOPTS=-D language=de + > .\make.bat html + + For PowerShell, run: + + .. code-block:: console + + > Set-Item env:SPHINXOPTS "-D language=de" + > .\make.bat html + +Congratulations! You got the translated documentation in the ``_build/html`` +directory. + +.. versionadded:: 1.3 + + :program:`sphinx-build` that is invoked by make command will build po files + into mo files. + + If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build` + command before :command:`make` command. + +Translating +~~~~~~~~~~~ + +Update your po files by new pot files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a document is updated, it is necessary to generate updated pot files and to +apply differences to translated po files. In order to apply the updates from a +pot file to the po file, use the :command:`sphinx-intl update` command. + +.. code-block:: console + + $ sphinx-intl update -p _build/gettext + + +Using Transifex service for team translation +-------------------------------------------- + +Transifex_ is one of several services that allow collaborative translation via a +web interface. It has a nifty Python-based command line client that makes it +easy to fetch and push translations. + +.. TODO: why use transifex? + + +#. Install `transifex-client`_. + + You need :command:`tx` command to upload resources (pot files). + + .. code-block:: console + + $ pip install transifex-client + + .. seealso:: `Transifex Client documentation`_ + +#. Create your Transifex_ account and create new project for your document. + + Currently, Transifex does not allow for a translation project to have more + than one version of the document, so you'd better include a version number in + your project name. + + For example: + + :Project ID: ``sphinx-document-test_1_0`` + :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/`` + +#. Create config files for :command:`tx` command. + + This process will create ``.tx/config`` in the current directory, as well as + a ``~/.transifexrc`` file that includes auth information. + + .. code-block:: console + + $ tx init + Creating .tx folder... + Transifex instance [https://www.transifex.com]: + ... + Please enter your transifex username: <transifex-username> + Password: <transifex-password> + ... + Done. + +#. Upload pot files to Transifex service. + + Register pot files to ``.tx/config`` file: + + .. code-block:: console + + $ cd /your/document/root + $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ + --transifex-project-name sphinx-document-test_1_0 + + and upload pot files: + + .. code-block:: console + + $ tx push -s + Pushing translations for resource sphinx-document-test_1_0.builders: + Pushing source file (locale/pot/builders.pot) + Resource does not exist. Creating... + ... + Done. + +#. Forward the translation on Transifex. + + .. TODO: write this section + +#. Pull translated po files and make translated HTML. + + Get translated catalogs and build mo files. For example, to build mo files + for German (de): + + .. code-block:: console + + $ cd /your/document/root + $ tx pull -l de + Pulling translations for resource sphinx-document-test_1_0.builders (...) + -> de: locale/de/LC_MESSAGES/builders.po + ... + Done. + + Invoke :command:`make html` (for BSD/GNU make): + + .. code-block:: console + + $ make -e SPHINXOPTS="-D language='de'" html + +That's all! + +.. tip:: Translating locally and on Transifex + + If you want to push all language's po files, you can be done by using + :command:`tx push -t` command. Watch out! This operation overwrites + translations in Transifex. + + In other words, if you have updated each in the service and local po files, + it would take much time and effort to integrate them. + + +Using Weblate service for team translation +------------------------------------------ + +Read more in `Weblate's documentation`_. + + +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 a `sphinx translation page`_ for Sphinx (master) documentation. + +1. Login to Transifex_ service. +2. Go to `sphinx translation page`_. +3. Click ``Request language`` and fill form. +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 + + +Translation progress and statistics +----------------------------------- + +.. versionadded:: 7.1.0 + +During the rendering process, +Sphinx marks each translatable node with a ``translated`` attribute, +indicating if a translation was found for the text in that node. + +The :confval:`translation_progress_classes` configuration value +can be used to add a class to each element, +depending on the value of the ``translated`` attribute. + +The ``|translation progress|`` substitution can be used to display the +percentage of nodes that have been translated on a per-document basis. + +.. rubric:: Footnotes + +.. [1] See the `GNU gettext utilities + <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_ + for details on that software suite. +.. [2] Because nobody expects the Spanish Inquisition! + +.. _`transifex-client`: https://pypi.org/project/transifex-client/ +.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/ +.. _Transifex: https://www.transifex.com/ +.. _Weblate's documentation: https://docs.weblate.org/en/latest/devel/sphinx.html +.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/ +.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/ diff --git a/doc/usage/advanced/websupport/api.rst b/doc/usage/advanced/websupport/api.rst new file mode 100644 index 0000000..79b51ee --- /dev/null +++ b/doc/usage/advanced/websupport/api.rst @@ -0,0 +1,80 @@ +.. _websupportapi: + +.. currentmodule:: sphinxcontrib.websupport + +The WebSupport Class +==================== + +.. class:: WebSupport + + The main API class for the web support package. All interactions with the + web support package should occur through this class. + + The class takes the following keyword arguments: + + srcdir + The directory containing reStructuredText source files. + + builddir + The directory that build data and static files should be placed in. This + should be used when creating a :class:`WebSupport` object that will be + used to build data. + + datadir + The directory that the web support data is in. This should be used when + creating a :class:`WebSupport` object that will be used to retrieve data. + + search + This may contain either a string (e.g. 'xapian') referencing a built-in + search adapter to use, or an instance of a subclass of + :class:`~.search.BaseSearch`. + + storage + This may contain either a string representing a database uri, or an + instance of a subclass of :class:`~.storage.StorageBackend`. If this is + not provided, a new sqlite database will be created. + + moderation_callback + A callable to be called when a new comment is added that is not + displayed. It must accept one argument: a dictionary representing the + comment that was added. + + staticdir + If the static files should be created in a different location + **and not in** ``'/static'``, this should be a string with the name of + that location (e.g. ``builddir + '/static_files'``). + + .. note:: + If you specify ``staticdir``, you will typically want to adjust + ``staticroot`` accordingly. + + staticroot + If the static files are not served from ``'/static'``, this should be a + string with the name of that location (e.g. ``'/static_files'``). + + docroot + If the documentation is not served from the base path of a URL, this + should be a string specifying that path (e.g. ``'docs'``). + + +.. versionchanged:: 1.6 + + WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport. + Please add ``sphinxcontrib-websupport`` package in your dependency and use + moved class instead. + + +Methods +------- + +.. automethod:: sphinxcontrib.websupport.WebSupport.build + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_document + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_data + +.. automethod:: sphinxcontrib.websupport.WebSupport.add_comment + +.. automethod:: sphinxcontrib.websupport.WebSupport.process_vote + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_search_results diff --git a/doc/usage/advanced/websupport/index.rst b/doc/usage/advanced/websupport/index.rst new file mode 100644 index 0000000..0816640 --- /dev/null +++ b/doc/usage/advanced/websupport/index.rst @@ -0,0 +1,16 @@ +.. _websupport: + +Sphinx Web Support +================== + +.. versionadded:: 1.1 + +Sphinx provides a Python API to easily integrate Sphinx documentation into your +web application. To learn more read the :ref:`websupportquickstart`. + +.. toctree:: + + quickstart + api + searchadapters + storagebackends diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst new file mode 100644 index 0000000..1cdd23f --- /dev/null +++ b/doc/usage/advanced/websupport/quickstart.rst @@ -0,0 +1,255 @@ +.. _websupportquickstart: + +Web Support Quick Start +======================= + +Building Documentation Data +---------------------------- + +To make use of the web support package in your application you'll need to build +the data it uses. This data includes pickle files representing documents, +search indices, and node data that is used to track where comments and other +things are in a document. To do this you will need to create an instance of the +:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method:: + + from sphinxcontrib.websupport import WebSupport + + support = WebSupport(srcdir='/path/to/rst/sources/', + builddir='/path/to/build/outdir', + search='xapian') + + support.build() + +This will read reStructuredText sources from ``srcdir`` and place the necessary +data in ``builddir``. The ``builddir`` will contain two sub-directories: one +named "data" that contains all the data needed to display documents, search +through documents, and add comments to documents. The other directory will be +called "static" and contains static files that should be served from "/static". + +.. note:: + + If you wish to serve static files from a path other than "/static", you can + do so by providing the *staticdir* keyword argument when creating the + :class:`~.WebSupport` object. + + +Integrating Sphinx Documents Into Your Webapp +---------------------------------------------- + +Now that the data is built, it's time to do something useful with it. Start off +by creating a :class:`~.WebSupport` object for your application:: + + from sphinxcontrib.websupport import WebSupport + + support = WebSupport(datadir='/path/to/the/data', + search='xapian') + +You'll only need one of these for each set of documentation you will be working +with. You can then call its :meth:`~.WebSupport.get_document` method to access +individual documents:: + + contents = support.get_document('contents') + +This will return a dictionary containing the following items: + +* **body**: The main body of the document as HTML +* **sidebar**: The sidebar of the document as HTML +* **relbar**: A div containing links to related documents +* **title**: The title of the document +* **css**: Links to CSS files used by Sphinx +* **script**: JavaScript containing comment options + +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 +<https://jinja.palletsprojects.com/>`_ is: + +.. code-block:: html+jinja + + {%- extends "layout.html" %} + + {%- block title %} + {{ document.title }} + {%- endblock %} + + {% block css %} + {{ super() }} + {{ document.css|safe }} + <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css"> + {% endblock %} + + {%- block script %} + {{ super() }} + {{ document.script|safe }} + {%- endblock %} + + {%- block relbar %} + {{ document.relbar|safe }} + {%- endblock %} + + {%- block body %} + {{ document.body|safe }} + {%- endblock %} + + {%- block sidebar %} + {{ document.sidebar|safe }} + {%- endblock %} + + +Authentication +~~~~~~~~~~~~~~ + +To use certain features such as voting, it must be possible to authenticate +users. The details of the authentication are left to your application. Once a +user has been authenticated you can pass the user's details to certain +:class:`~.WebSupport` methods using the *username* and *moderator* keyword +arguments. The web support package will store the username with comments and +votes. The only caveat is that if you allow users to change their username you +must update the websupport package's data:: + + support.update_username(old_username, new_username) + +*username* should be a unique string which identifies a user, and *moderator* +should be a boolean representing whether the user has moderation privileges. +The default value for *moderator* is ``False``. + +An example `Flask <https://flask.palletsprojects.com/>`_ function that checks +whether a user is logged in and then retrieves a document is:: + + from sphinxcontrib.websupport.errors import * + + @app.route('/<path:docname>') + def doc(docname): + username = g.user.name if g.user else '' + moderator = g.user.moderator if g.user else False + try: + document = support.get_document(docname, username, moderator) + except DocumentNotFoundError: + abort(404) + return render_template('doc.html', document=document) + +The first thing to notice is that the *docname* is just the request path. This +makes accessing the correct document easy from a single view. If the user is +authenticated, then the username and moderation status are passed along with the +docname to :meth:`~.WebSupport.get_document`. The web support package will then +add this data to the ``COMMENT_OPTIONS`` that are used in the template. + +.. note:: + + This only works if your documentation is served from your + document root. If it is served from another directory, you will + need to prefix the url route with that directory, and give the `docroot` + keyword argument when creating the web support object:: + + support = WebSupport(..., docroot='docs') + + @app.route('/docs/<path:docname>') + + +Performing Searches +------------------- + +To use the search form built-in to the Sphinx sidebar, create a function to +handle requests to the URL 'search' relative to the documentation root. The +user's search query will be in the GET parameters, with the key `q`. Then use +the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to +retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that +would be like this:: + + @app.route('/search') + def search(): + q = request.args.get('q') + document = support.get_search_results(q) + return render_template('doc.html', document=document) + +Note that we used the same template to render our search results as we did to +render our documents. That's because :meth:`~.WebSupport.get_search_results` +returns a context dict in the same format that :meth:`~.WebSupport.get_document` +does. + + +Comments & Proposals +-------------------- + +Now that this is done it's time to define the functions that handle the AJAX +calls from the script. You will need three functions. The first function is +used to add a new comment, and will call the web support method +:meth:`~.WebSupport.add_comment`:: + + @app.route('/docs/add_comment', methods=['POST']) + def add_comment(): + parent_id = request.form.get('parent', '') + node_id = request.form.get('node', '') + text = request.form.get('text', '') + proposal = request.form.get('proposal', '') + username = g.user.name if g.user is not None else 'Anonymous' + comment = support.add_comment(text, node_id='node_id', + parent_id='parent_id', + username=username, proposal=proposal) + return jsonify(comment=comment) + +You'll notice that both a ``parent_id`` and ``node_id`` are sent with the +request. If the comment is being attached directly to a node, ``parent_id`` +will be empty. If the comment is a child of another comment, then ``node_id`` +will be empty. Then next function handles the retrieval of comments for a +specific node, and is aptly named +:meth:`~sphinxcontrib.websupport.WebSupport.get_data`:: + + @app.route('/docs/get_comments') + def get_comments(): + username = g.user.name if g.user else None + moderator = g.user.moderator if g.user else False + node_id = request.args.get('node', '') + data = support.get_data(node_id, username, moderator) + return jsonify(**data) + +The final function that is needed will call :meth:`~.WebSupport.process_vote`, +and will handle user votes on comments:: + + @app.route('/docs/process_vote', methods=['POST']) + def process_vote(): + if g.user is None: + abort(401) + comment_id = request.form.get('comment_id') + value = request.form.get('value') + if value is None or comment_id is None: + abort(400) + support.process_vote(comment_id, g.user.id, value) + return "success" + + +Comment Moderation +------------------ + +By default, all comments added through :meth:`~.WebSupport.add_comment` are +automatically displayed. If you wish to have some form of moderation, you can +pass the ``displayed`` keyword argument:: + + comment = support.add_comment(text, node_id='node_id', + parent_id='parent_id', + username=username, proposal=proposal, + displayed=False) + +You can then create a new view to handle the moderation of comments. It +will be called when a moderator decides a comment should be accepted and +displayed:: + + @app.route('/docs/accept_comment', methods=['POST']) + def accept_comment(): + moderator = g.user.moderator if g.user else False + comment_id = request.form.get('id') + support.accept_comment(comment_id, moderator=moderator) + return 'OK' + +Rejecting comments happens via comment deletion. + +To perform a custom action (such as emailing a moderator) when a new comment is +added but not displayed, you can pass callable to the :class:`~.WebSupport` +class when instantiating your support object:: + + def moderation_callback(comment): + """Do something...""" + + support = WebSupport(..., moderation_callback=moderation_callback) + +The moderation callback must take one argument, which will be the same comment +dict that is returned by :meth:`.WebSupport.add_comment`. diff --git a/doc/usage/advanced/websupport/searchadapters.rst b/doc/usage/advanced/websupport/searchadapters.rst new file mode 100644 index 0000000..262d666 --- /dev/null +++ b/doc/usage/advanced/websupport/searchadapters.rst @@ -0,0 +1,49 @@ +.. _searchadapters: + +.. currentmodule:: sphinxcontrib.websupport.search + +Search Adapters +=============== + +To create a custom search adapter you will need to subclass the +:class:`BaseSearch` class. Then create an instance of the new class and pass +that as the `search` keyword argument when you create the :class:`~.WebSupport` +object:: + + support = WebSupport(srcdir=srcdir, + builddir=builddir, + search=MySearch()) + +For more information about creating a custom search adapter, please see the +documentation of the :class:`BaseSearch` class below. + +.. class:: BaseSearch + + Defines an interface for search adapters. + +.. versionchanged:: 1.6 + + BaseSearch class is moved to sphinxcontrib.websupport.search from + sphinx.websupport.search. + +Methods +------- + +The following methods are defined in the BaseSearch class. Some methods do not +need to be overridden, but some (:meth:`~BaseSearch.add_document` and +:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a +working example, look at the built-in adapter for whoosh. + +.. automethod:: BaseSearch.init_indexing + +.. automethod:: BaseSearch.finish_indexing + +.. automethod:: BaseSearch.feed + +.. automethod:: BaseSearch.add_document + +.. automethod:: BaseSearch.query + +.. automethod:: BaseSearch.handle_query + +.. automethod:: BaseSearch.extract_context diff --git a/doc/usage/advanced/websupport/storagebackends.rst b/doc/usage/advanced/websupport/storagebackends.rst new file mode 100644 index 0000000..ccb00b6 --- /dev/null +++ b/doc/usage/advanced/websupport/storagebackends.rst @@ -0,0 +1,49 @@ +.. _storagebackends: + +.. currentmodule:: sphinxcontrib.websupport.storage + +Storage Backends +================ + +To create a custom storage backend you will need to subclass the +:class:`StorageBackend` class. Then create an instance of the new class and +pass that as the `storage` keyword argument when you create the +:class:`~.WebSupport` object:: + + support = WebSupport(srcdir=srcdir, + builddir=builddir, + storage=MyStorage()) + +For more information about creating a custom storage backend, please see the +documentation of the :class:`StorageBackend` class below. + +.. class:: StorageBackend + + Defines an interface for storage backends. + +.. versionchanged:: 1.6 + + StorageBackend class is moved to sphinxcontrib.websupport.storage from + sphinx.websupport.storage. + + +Methods +------- + +.. automethod:: StorageBackend.pre_build + +.. automethod:: StorageBackend.add_node + +.. automethod:: StorageBackend.post_build + +.. automethod:: StorageBackend.add_comment + +.. automethod:: StorageBackend.delete_comment + +.. automethod:: StorageBackend.get_data + +.. automethod:: StorageBackend.process_vote + +.. automethod:: StorageBackend.update_username + +.. automethod:: StorageBackend.accept_comment diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst new file mode 100644 index 0000000..ce2c5dc --- /dev/null +++ b/doc/usage/builders/index.rst @@ -0,0 +1,565 @@ +.. _builders: + +======== +Builders +======== + +.. module:: sphinx.builders + :synopsis: Available built-in builder classes. + +These are the built-in Sphinx builders. More builders can be added by +:doc:`extensions </usage/extensions/index>`. + +The builder's "name" must be given to the **-b** command-line option of +:program:`sphinx-build` to select a builder. + + +.. module:: sphinx.builders.html +.. class:: StandaloneHTMLBuilder + + This is the standard HTML builder. Its output is a directory with HTML + files, complete with style sheets and optionally the reST sources. There are + quite a few configuration values that customize the output of this builder, + see the chapter :ref:`html-options` for details. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinx.builders.dirhtml +.. class:: DirectoryHTMLBuilder + + This is a subclass of the standard HTML builder. Its output is a directory + with HTML files, where each file is called ``index.html`` and placed in a + subdirectory named like its page name. For example, the document + ``markup/rest.rst`` will not result in an output file ``markup/rest.html``, + but ``markup/rest/index.html``. When generating links between pages, the + ``index.html`` is omitted, so that the URL would look like ``markup/rest/``. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 0.6 + +.. module:: sphinx.builders.singlehtml +.. class:: SingleFileHTMLBuilder + + This is an HTML builder that combines the whole project in one output file. + (Obviously this only works with smaller projects.) The file is named like + the root document. No indices will be generated. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.0 + +.. module:: sphinxcontrib.htmlhelp +.. class:: HTMLHelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates HTML Help support files that allow the Microsoft HTML Help + Workshop to compile them into a CHM file. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinxcontrib.qthelp +.. class:: QtHelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates `Qt help`_ collection support files that allow the Qt + collection generator to compile them. + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.qthelp from sphinx.builders package. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html + +.. module:: sphinxcontrib.applehelp +.. class:: AppleHelpBuilder + + This builder produces an Apple Help Book based on the same output as the + standalone HTML builder. + + If the source directory contains any ``.lproj`` folders, the one + corresponding to the selected language will have its contents merged with + the generated output. These folders will be ignored by all other + documentation types. + + In order to generate a valid help book, this builder requires the command + line tool :program:`hiutil`, which is only available on Mac OS X 10.6 and + above. You can disable the indexing step by setting + :confval:`applehelp_disable_external_tools` to ``True``, in which case the + output will not be valid until :program:`hiutil` has been run on all of the + ``.lproj`` folders within the bundle. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.3 + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.applehelp from sphinx.builders package. + +.. module:: sphinxcontrib.devhelp +.. class:: DevhelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates `GNOME Devhelp <https://wiki.gnome.org/Apps/Devhelp>`__ + support file that allows the GNOME Devhelp reader to view them. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.devhelp from sphinx.builders package. + +.. module:: sphinx.builders.epub3 +.. class:: Epub3Builder + + This builder produces the same output as the standalone HTML builder, but + also generates an *epub* file for ebook readers. See :ref:`epub-faq` for + details about it. For definition of the epub format, have a look at + `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_. + The builder creates *EPUB 3* files. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + + Since Sphinx 1.5, the epub3 builder is used as the default epub builder. + +.. module:: sphinx.builders.latex +.. class:: LaTeXBuilder + + This builder produces LaTeX source files in the output directory. The + actual PDF builds happen inside this output directory and need to be + triggered in a second step. This can be done via + :program:`make all-pdf` there. + To combine the two steps into only one, use :option:`sphinx-build -M` + (i.e. ``-M latexpdf`` not ``-b latexpdf``) or :program:`make latexpdf` + at the project root. + + See :confval:`latex_documents` and the chapter :ref:`latex-options` for + available options. + + PDF builds need a sufficiently complete LaTeX installation. + The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, + whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, + but PDF builds can be successfully done on much older LaTeX installations. + + At any rate, on Ubuntu for example, following packages must all be present: + + * ``texlive-latex-recommended`` + * ``texlive-fonts-recommended`` + * ``tex-gyre`` (if :confval:`latex_engine` left to default) + * ``texlive-latex-extra`` + * ``latexmk`` + + .. versionchanged:: 4.0.0 + TeX Gyre fonts now required for ``'pdflatex'`` engine (default). + + Additional packages are needed in some circumstances: + + * ``texlive-lang-cyrillic`` for Cyrillic (and also then + ``cm-super`` if using the default fonts), + * ``texlive-lang-greek`` for Greek (and also then + ``cm-super`` if using the 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 either + ``'xelatex'`` or ``'lualatex'``. + + .. note:: + + Since 1.6, ``make latexpdf`` uses on GNU/Linux and macOS + :program:`latexmk`, as it + makes sure the needed number of runs is automatically executed. + On Windows the PDF builds execute a fix number of LaTeX runs + (three, then ``makeindex``, then two more). + + One can pass to ``latexmk`` options via the ``LATEXMKOPTS`` + Makefile variable. For example: + + .. code-block:: console + + make latexpdf LATEXMKOPTS="-silent" + + reduces console output to a minimum. + + Also, if ``latexmk`` is at version 4.52b or higher (January 2017) + ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case + of numerous graphics inclusions. + + To pass options directly to the ``(pdf|xe|lua)latex`` binary, use + variable ``LATEXOPTS``, for example: + + .. code-block:: console + + make latexpdf LATEXOPTS="--halt-on-error" + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +Note that a direct PDF builder is being provided by `rinohtype`_. The builder's +name is ``rinoh``. Refer to the `rinohtype manual`_ for details. + +.. _rinohtype: https://github.com/brechtm/rinohtype +.. _rinohtype manual: https://www.mos6581.org/rinohtype/master/quickstart.html#sphinx-builder + +.. module:: sphinx.builders.text +.. class:: TextBuilder + + This builder produces a text file for each reST file -- this is almost the + same as the reST source, but with much of the markup stripped for better + readability. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 0.4 + +.. module:: sphinx.builders.manpage +.. class:: ManualPageBuilder + + This builder produces manual pages in the groff format. You have to specify + which documents are to be included in which manual pages via the + :confval:`man_pages` configuration value. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.0 + + +.. module:: sphinx.builders.texinfo +.. class:: TexinfoBuilder + + This builder produces Texinfo files that can be processed into Info files by + the :program:`makeinfo` program. You have to specify which documents are to + be included in which Texinfo files via the :confval:`texinfo_documents` + configuration value. + + The Info format is the basis of the on-line help system used by GNU Emacs and + the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more + details. The Texinfo format is the official documentation system used by the + GNU project. More information on Texinfo can be found at + `<https://www.gnu.org/software/texinfo/>`_. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.1 + + +.. currentmodule:: sphinxcontrib.serializinghtml +.. class:: SerializingHTMLBuilder + + This builder uses a module that implements the Python serialization API + (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated + HTML documentation. The pickle builder is a subclass of it. + + A concrete subclass of this builder serializing to the `PHP serialization`_ + format could look like this:: + + import phpserialize + + class PHPSerializedBuilder(SerializingHTMLBuilder): + name = 'phpserialized' + implementation = phpserialize + out_suffix = '.file.phpdump' + globalcontext_filename = 'globalcontext.phpdump' + searchindex_filename = 'searchindex.phpdump' + + .. _PHP serialization: https://pypi.org/project/phpserialize/ + + .. attribute:: implementation + + A module that implements `dump()`, `load()`, `dumps()` and `loads()` + functions that conform to the functions with the same names from the + pickle module. Known modules implementing this interface are + `simplejson`, `phpserialize`, `plistlib`, and others. + + .. attribute:: out_suffix + + The suffix for all regular files. + + .. attribute:: globalcontext_filename + + The filename for the file that contains the "global context". This + is a dict with some general configuration values such as the name + of the project. + + .. attribute:: searchindex_filename + + The filename for the search index Sphinx generates. + + See :ref:`serialization-details` for details about the output format. + + .. versionadded:: 0.5 + +.. class:: PickleHTMLBuilder + + This builder produces a directory with pickle files containing mostly HTML + fragments and TOC information, for use of a web application (or custom + postprocessing tool) that doesn't use the standard HTML templates. + + See :ref:`serialization-details` for details about the output format. + + .. autoattribute:: name + + The old name ``web`` still works as well. + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + The file suffix is ``.fpickle``. The global context is called + ``globalcontext.pickle``, the search index ``searchindex.pickle``. + +.. class:: JSONHTMLBuilder + + This builder produces a directory with JSON files containing mostly HTML + fragments and TOC information, for use of a web application (or custom + postprocessing tool) that doesn't use the standard HTML templates. + + See :ref:`serialization-details` for details about the output format. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + The file suffix is ``.fjson``. The global context is called + ``globalcontext.json``, the search index ``searchindex.json``. + + .. versionadded:: 0.5 + +.. module:: sphinx.builders.gettext +.. class:: MessageCatalogBuilder + + This builder produces gettext-style message catalogs. Each top-level file or + subdirectory grows a single ``.pot`` catalog template. + + See the documentation on :ref:`intl` for further reference. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.1 + +.. module:: sphinx.builders.changes +.. class:: ChangesBuilder + + This builder produces an HTML overview of all :rst:dir:`versionadded`, + :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the + current :confval:`version`. This is useful to generate a ChangeLog file, for + example. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinx.builders.dummy +.. class:: DummyBuilder + + This builder produces no output. The input is only parsed and checked for + consistency. This is useful for linting purposes. + + .. autoattribute:: name + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.4 + +.. module:: sphinx.builders.linkcheck +.. class:: CheckExternalLinksBuilder + + This builder scans all documents for external links, tries to open them with + ``requests``, and writes an overview which ones are broken and redirected to + standard output and to :file:`output.txt` in the output directory. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionchanged:: 1.5 + + Since Sphinx 1.5, the linkcheck builder uses the requests module. + + .. versionchanged:: 3.4 + + The linkcheck builder retries links when servers apply rate limits. + +.. module:: sphinx.builders.xml +.. class:: XMLBuilder + + This builder produces Docutils-native XML files. The output can be + transformed with standard XML tools such as XSLT processors into arbitrary + final forms. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.2 + +.. class:: PseudoXMLBuilder + + This builder is used for debugging the Sphinx/Docutils "Reader to Transform + to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files + where nesting is indicated by indentation (no end-tags). External + attributes for all elements are output, and internal attributes for any + leftover "pending" elements are also given. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.2 + + +Built-in Sphinx extensions that offer more builders are: + +* :mod:`~sphinx.ext.doctest` +* :mod:`~sphinx.ext.coverage` + + +.. _serialization-details: + +Serialization builder details +----------------------------- + +All serialization builders outputs one file per source file and a few special +files. They also copy the reST source files in the directory ``_sources`` +under the output directory. + +The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle +serialization interface. + +The files per source file have the extensions of +:attr:`~.SerializingHTMLBuilder.out_suffix`, and are arranged in directories +just as the source files are. They unserialize to a dictionary (or dictionary +like structure) with these keys: + +``body`` + The HTML "body" (that is, the HTML rendering of the source file), as rendered + by the HTML translator. + +``title`` + The title of the document, as HTML (may contain markup). + +``toc`` + The table of contents for the file, rendered as an HTML ``<ul>``. + +``display_toc`` + A boolean that is ``True`` if the ``toc`` contains more than one entry. + +``current_page_name`` + The document name of the current file. + +``parents``, ``prev`` and ``next`` + Information about related chapters in the TOC tree. Each relation is a + dictionary with the keys ``link`` (HREF for the relation) and ``title`` + (title of the related document, as HTML). ``parents`` is a list of + relations, while ``prev`` and ``next`` are a single relation. + +``sourcename`` + The name of the source file under ``_sources``. + +The special files are located in the root output directory. They are: + +:attr:`.SerializingHTMLBuilder.globalcontext_filename` + A pickled dict with these keys: + + ``project``, ``copyright``, ``release``, ``version`` + The same values as given in the configuration file. + + ``style`` + :confval:`html_style`. + + ``last_updated`` + Date of last build. + + ``builder`` + Name of the used builder, in the case of pickles this is always + ``'pickle'``. + + ``titles`` + A dictionary of all documents' titles, as HTML strings. + +:attr:`.SerializingHTMLBuilder.searchindex_filename` + An index that can be used for searching the documentation. It is a pickled + list with these entries: + + * A list of indexed docnames. + * A list of document titles, as HTML strings, in the same order as the first + list. + * A dict mapping word roots (processed by an English-language stemmer) to a + list of integers, which are indices into the first list. + +``environment.pickle`` + The build environment. This is always a pickle file, independent of the + builder and a copy of the environment that was used when the builder was + started. + + .. todo:: Document common members. + + Unlike the other pickle files this pickle file requires that the ``sphinx`` + package is available on unpickling. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst new file mode 100644 index 0000000..d440132 --- /dev/null +++ b/doc/usage/configuration.rst @@ -0,0 +1,3094 @@ +.. highlight:: python + +.. _build-config: + +============= +Configuration +============= + +.. module:: conf + :synopsis: Build configuration file. + +The :term:`configuration directory` must contain a file named :file:`conf.py`. +This file (containing Python code) is called the "build configuration file" +and contains (almost) all configuration needed to customize Sphinx input +and output behavior. + +An optional file `docutils.conf`_ can be added to the configuration +directory to adjust `Docutils`_ configuration if not otherwise overridden or +set by Sphinx. + +.. _`docutils`: https://docutils.sourceforge.io/ +.. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html + +The configuration file is executed as Python code at build time (using +:func:`importlib.import_module`, and with the current directory set to its +containing directory), and therefore can execute arbitrarily complex code. +Sphinx then reads simple names from the file's namespace as its configuration. + +Important points to note: + +* If not otherwise documented, values must be strings, and their default is the + empty string. + +* The term "fully-qualified name" refers to a string that names an importable + Python object inside a module; for example, the FQN + ``"sphinx.builders.Builder"`` means the ``Builder`` class in the + ``sphinx.builders`` module. + +* Remember that document names use ``/`` as the path separator and don't + contain the file name extension. + +* Since :file:`conf.py` is read as a Python file, the usual rules apply for + encodings and Unicode support. + +* The contents of the config namespace are pickled (so that Sphinx can find out + when configuration changes), so it may not contain unpickleable values -- + delete them from the namespace with ``del`` if appropriate. Modules are + removed automatically, so you don't need to ``del`` your imports after use. + + .. _conf-tags: + +* There is a special object named ``tags`` available in the config file. + It can be used to query and change the tags (see :ref:`tags`). Use + ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` + to change. Only tags set via the ``-t`` command-line option or via + ``tags.add('tag')`` can be queried using ``tags.has('tag')``. + Note that the current builder tag is not available in ``conf.py``, as it is + created *after* the builder is initialized. + + +Project information +------------------- + +.. confval:: project + + The documented project's name. + +.. confval:: author + + The author name(s) of the document. The default value is ``'unknown'``. + +.. confval:: copyright + + A copyright statement in the style ``'2008, Author Name'``. + + .. versionchanged:: 7.1 + The value may now be a sequence of copyright statements in the above form, + which will be displayed each to their own line. + +.. confval:: project_copyright + + An alias of :confval:`copyright`. + + .. versionadded:: 3.5 + +.. confval:: version + + The major project version, used as the replacement for ``|version|``. For + example, for the Python documentation, this may be something like ``2.6``. + +.. confval:: release + + The full project version, used as the replacement for ``|release|`` and + e.g. in the HTML templates. For example, for the Python documentation, this + may be something like ``2.6.0rc1``. + + If you don't need the separation provided between :confval:`version` and + :confval:`release`, just set them both to the same value. + + +General configuration +--------------------- + +.. confval:: extensions + + A list of strings that are module names of :doc:`extensions + <extensions/index>`. These can be extensions coming with Sphinx (named + ``sphinx.ext.*``) or custom ones. + + Note that you can extend :data:`sys.path` within the conf file if your + extensions live in another directory -- but make sure you use absolute paths. + If your extension path is relative to the :term:`configuration directory`, + use :func:`os.path.abspath` like so:: + + import sys, os + + sys.path.append(os.path.abspath('sphinxext')) + + extensions = ['extname'] + + That way, you can load an extension called ``extname`` from the subdirectory + ``sphinxext``. + + The configuration file itself can be an extension; for that, you only need + to provide a :func:`setup` function in it. + +.. confval:: source_suffix + + The file extensions of source files. Sphinx considers the files with this + suffix as sources. The value can be a dictionary mapping file extensions + to file types. For example:: + + source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'restructuredtext', + '.md': 'markdown', + } + + By default, Sphinx only supports ``'restructuredtext'`` file type. You can + add a new file type using source parser extensions. Please read a document + of the extension to know which file type the extension supports. + + The value may also be a list of file extensions: then Sphinx will consider + that they all map to the ``'restructuredtext'`` file type. + + Default is ``{'.rst': 'restructuredtext'}``. + + .. note:: file extensions have to start with a dot (e.g. ``.rst``). + + .. versionchanged:: 1.3 + Can now be a list of extensions. + + .. versionchanged:: 1.8 + Support file type mapping + +.. confval:: source_encoding + + The encoding of all reST source files. The recommended encoding, and the + default value, is ``'utf-8-sig'``. + + .. versionadded:: 0.5 + Previously, Sphinx accepted only UTF-8 encoded sources. + +.. confval:: source_parsers + + If given, a dictionary of parser classes for different source suffices. The + keys are the suffix, the values can be either a class or a string giving a + fully-qualified name of a parser class. The parser class can be either + ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a + suffix that is not in the dictionary will be parsed with the default + reStructuredText parser. + + For example:: + + source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + + .. note:: + + Refer to :doc:`/usage/markdown` for more information on using Markdown + with Sphinx. + + .. versionadded:: 1.3 + + .. deprecated:: 1.8 + Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register + a source parser. Please use it instead. + +.. confval:: master_doc + + Same as :confval:`root_doc`. + + .. versionchanged:: 4.0 + Renamed ``master_doc`` to ``root_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 ``root_doc`` from ``master_doc``. + +.. confval:: exclude_patterns + + A list of glob-style patterns [1]_ that should be excluded when looking for + source files. They are matched against the source file names relative + to the source directory, using slashes as directory separators on all + platforms. + + Example patterns: + + - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file + - ``'library/xml'`` -- ignores the ``library/xml`` directory + - ``'library/xml*'`` -- ignores all files and directories starting with + ``library/xml`` + - ``'**/.svn'`` -- ignores all ``.svn`` directories + + :confval:`exclude_patterns` is also consulted when looking for static files + in :confval:`html_static_path` and :confval:`html_extra_path`. + + .. versionadded:: 1.0 + +.. confval:: include_patterns + + A list of glob-style patterns [1]_ that are used to find source files. They + are matched against the source file names relative to the source directory, + using slashes as directory separators on all platforms. The default is ``**``, + meaning that all files are recursively included from the source directory. + + Example patterns: + + - ``'**'`` -- all files in the source directory and subdirectories, recursively + - ``'library/xml'`` -- just the ``library/xml`` directory + - ``'library/xml*'`` -- all files and directories starting with ``library/xml`` + - ``'**/doc'`` -- all ``doc`` directories (this might be useful if + documentation is co-located with source files) + + .. versionadded:: 5.1 + +.. confval:: templates_path + + A list of paths that contain extra templates (or templates that overwrite + builtin/theme-specific templates). Relative paths are taken as relative to + the configuration directory. + + .. versionchanged:: 1.3 + As these files are not meant to be built, they are automatically added to + :confval:`exclude_patterns`. + +.. confval:: template_bridge + + A string with the fully-qualified name of a callable (or simply a class) + that returns an instance of :class:`~sphinx.application.TemplateBridge`. + This instance is then used to render HTML documents, and possibly the output + of other builders (currently the changes builder). (Note that the template + bridge must be made theme-aware if HTML themes are to be used.) + +.. confval:: rst_epilog + + .. index:: pair: global; substitutions + + A string of reStructuredText that will be included at the end of every source + file that is read. This is a possible place to add substitutions that should + be available in every file (another being :confval:`rst_prolog`). An + example:: + + rst_epilog = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 0.6 + +.. confval:: rst_prolog + + .. index:: pair: global; substitutions + + A string of reStructuredText that will be included at the beginning of every + source file that is read. This is a possible place to add substitutions that + should be available in every file (another being :confval:`rst_epilog`). An + example:: + + rst_prolog = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 1.0 + +.. confval:: primary_domain + + .. index:: default; domain + primary; domain + + The name of the default :doc:`domain </usage/restructuredtext/domains>`. + Can also be ``None`` to disable a default domain. The default is ``'py'``. + Those objects in other domains (whether the domain name is given explicitly, + or selected by a :rst:dir:`default-domain` directive) will have the domain + name explicitly prepended when named (e.g., when the default domain is C, + Python functions will be named "Python function", not just "function"). + + .. versionadded:: 1.0 + +.. confval:: default_role + + .. index:: default; role + + The name of a reST role (builtin or Sphinx extension) to use as the default + role, that is, for text marked up ```like this```. This can be set to + ``'py:obj'`` to make ```filter``` a cross-reference to the Python function + "filter". The default is ``None``, which doesn't reassign the default role. + + The default role can always be set within individual documents using the + standard reST :dudir:`default-role` directive. + + .. versionadded:: 0.4 + +.. confval:: keep_warnings + + If true, keep warnings as "system message" paragraphs in the built + documents. Regardless of this setting, warnings are always written to the + standard error stream when ``sphinx-build`` is run. + + The default is ``False``, the pre-0.5 behavior was to always keep them. + + .. versionadded:: 0.5 + +.. confval:: suppress_warnings + + A list of warning types to suppress arbitrary warning messages. + + Sphinx supports following warning types: + + * ``app.add_node`` + * ``app.add_directive`` + * ``app.add_role`` + * ``app.add_generic_role`` + * ``app.add_source_parser`` + * ``autosectionlabel.*`` + * ``download.not_readable`` + * ``epub.unknown_project_files`` + * ``epub.duplicated_toc_entry`` + * ``i18n.inconsistent_references`` + * ``index`` + * ``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.circular`` + * ``toc.excluded`` + * ``toc.not_readable`` + * ``toc.secnum`` + + You can choose from these types. You can also give only the first + component to exclude all warnings attached to it. + + Now, this option should be considered *experimental*. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + + Added ``misc.highlighting_failure`` + + .. versionchanged:: 1.5.1 + + Added ``epub.unknown_project_files`` + + .. versionchanged:: 1.6 + + Added ``ref.footnote`` + + .. versionchanged:: 2.1 + + Added ``autosectionlabel.*`` + + .. versionchanged:: 3.3.0 + + Added ``epub.duplicated_toc_entry`` + + .. versionchanged:: 4.3 + + Added ``toc.excluded`` and ``toc.not_readable`` + + .. versionadded:: 4.5 + + Added ``i18n.inconsistent_references`` + + .. versionadded:: 7.1 + + Added ``index`` warning type. + +.. confval:: needs_sphinx + + If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will + compare it with its version and refuse to build if it is too old. Default + is no requirement. + + .. versionadded:: 1.0 + + .. versionchanged:: 1.4 + also accepts micro version string + +.. confval:: needs_extensions + + This value can be a dictionary specifying version requirements for + extensions in :confval:`extensions`, e.g. ``needs_extensions = + {'sphinxcontrib.something': '1.5'}``. The version strings should be in the + form ``major.minor``. Requirements do not have to be specified for all + extensions, only for those you want to check. + + This requires that the extension specifies its version to Sphinx (see + :ref:`dev-extensions` for how to do that). + + .. versionadded:: 1.3 + +.. confval:: manpages_url + + A URL to cross-reference :rst:role:`manpage` roles. If this is + defined to ``https://manpages.debian.org/{path}``, the + :literal:`:manpage:`man(1)`` role will link to + <https://manpages.debian.org/man(1)>. The patterns available are: + + * ``page`` - the manual page (``man``) + * ``section`` - the manual section (``1``) + * ``path`` - the original manual page and section specified (``man(1)``) + + This also supports manpages specified as ``man.1``. + + .. note:: This currently affects only HTML writers but could be + expanded in the future. + + .. versionadded:: 1.7 + +.. confval:: nitpicky + + If true, Sphinx will warn about *all* references where the target cannot be + found. Default is ``False``. You can activate this mode temporarily using + the :option:`-n <sphinx-build -n>` command-line switch. + + .. versionadded:: 1.0 + +.. confval:: nitpick_ignore + + A set or list of ``(type, target)`` tuples (by default empty) that should be + ignored when generating warnings in "nitpicky mode". Note that ``type`` + should include the domain name if present. Example entries would be + ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. + + .. versionadded:: 1.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + +.. confval:: nitpick_ignore_regex + + An extended version of :confval:`nitpick_ignore`, which instead interprets + the ``type`` and ``target`` strings as regular expressions. Note, that the + regular expression must match the whole string (as if the ``^`` and ``$`` + markers were inserted). + + For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings + for all python entities that start with ``'foo'`` and have ``'bar.B'`` in + them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or + ``('py:class', 'food.bar.Barman')``. + + .. versionadded:: 4.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + +.. confval:: numfig + + If true, figures, tables and code-blocks are automatically numbered if they + have a caption. The :rst:role:`numref` role is enabled. + Obeyed so far only by HTML and LaTeX builders. Default is ``False``. + + .. note:: + + The LaTeX builder always assigns numbers whether this option is enabled + or not. + + .. versionadded:: 1.3 + +.. confval:: numfig_format + + A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and + ``'section'`` to strings that are used for format of figure numbers. + As a special character, ``%s`` will be replaced to figure number. + + Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for + ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for + ``'section'``. + + .. versionadded:: 1.3 + +.. confval:: numfig_secnum_depth + + - if set to ``0``, figures, tables and code-blocks are continuously numbered + starting at ``1``. + - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x`` + the section number (top level sectioning; no ``x.`` if no section). + This naturally applies only if section numbering has been activated via + the ``:numbered:`` option of the :rst:dir:`toctree` directive. + - ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in + a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a + section and ``1``, ``2``, ... if not in any top level section.) + - etc... + + .. versionadded:: 1.3 + + .. versionchanged:: 1.7 + The LaTeX builder obeys this setting (if :confval:`numfig` is set to + ``True``). + +.. confval:: smartquotes + + If true, the `Docutils Smart Quotes transform`__, originally based on + `SmartyPants`__ (limited to English) and currently applying to many + languages, will be used to convert quotes and dashes to typographically + correct entities. Default: ``True``. + + __ https://docutils.sourceforge.io/docs/user/smartquotes.html + __ https://daringfireball.net/projects/smartypants/ + + .. versionadded:: 1.6.6 + It replaces deprecated :confval:`html_use_smartypants`. + It applies by default to all builders except ``man`` and ``text`` + (see :confval:`smartquotes_excludes`.) + + A `docutils.conf`__ file located in the configuration directory (or a + global :file:`~/.docutils` file) is obeyed unconditionally if it + *deactivates* smart quotes via the corresponding `Docutils option`__. But + if it *activates* them, then :confval:`smartquotes` does prevail. + + __ https://docutils.sourceforge.io/docs/user/config.html + __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes + +.. confval:: smartquotes_action + + 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 + + __ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ + +.. confval:: smartquotes_excludes + + This is a ``dict`` whose default is:: + + {'languages': ['ja'], 'builders': ['man', 'text']} + + Each entry gives a sufficient condition to ignore the + :confval:`smartquotes` setting and deactivate the Smart Quotes transform. + Accepted keys are as above ``'builders'`` or ``'languages'``. + The values are lists. + + .. note:: Currently, in case of invocation of :program:`make` with multiple + targets, the first target name is the only one which is tested against + the ``'builders'`` entry and it decides for all. Also, a ``make text`` + following ``make html`` needs to be issued in the form ``make text + O="-E"`` to force re-parsing of source files, as the cached ones are + already transformed. On the other hand the issue does not arise with + direct usage of :program:`sphinx-build` as it caches + (in its default usage) the parsed source files in per builder locations. + + .. hint:: An alternative way to effectively deactivate (or customize) the + smart quotes for a given builder, for example ``latex``, is to use + ``make`` this way: + + .. code-block:: console + + make latex O="-D smartquotes_action=" + + This can follow some ``make html`` with no problem, in contrast to the + situation from the prior note. + + .. versionadded:: 1.6.6 + +.. confval:: user_agent + + A User-Agent of Sphinx. It is used for a header on HTTP access (ex. + linkcheck, intersphinx and so on). Default is ``"Sphinx/X.Y.Z + requests/X.Y.Z python/X.Y.Z"``. + + .. versionadded:: 2.3 + +.. confval:: tls_verify + + If true, Sphinx verifies server certifications. Default is ``True``. + + .. versionadded:: 1.5 + +.. confval:: tls_cacerts + + A path to a certification file of CA or a path to directory which + contains the certificates. This also allows a dictionary mapping + hostname to the path to certificate file. + The certificates are used to verify server certifications. + + .. versionadded:: 1.5 + + .. tip:: Sphinx uses requests_ as a HTTP library internally. + Therefore, Sphinx refers a certification file on the + directory pointed ``REQUESTS_CA_BUNDLE`` environment + variable if ``tls_cacerts`` not set. + + .. _requests: https://requests.readthedocs.io/en/master/ + +.. confval:: today + today_fmt + + These values determine how to format the current date, used as the + replacement for ``|today|``. + + * If you set :confval:`today` to a non-empty value, it is used. + * Otherwise, the current time is formatted using :func:`time.strftime` and + the format given in :confval:`today_fmt`. + + The default is now :confval:`today` and a :confval:`today_fmt` of ``'%b %d, + %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent + format for the selected locale). + +.. confval:: highlight_language + + The default language to highlight source code in. The default is + ``'default'``. It is similar to ``'python3'``; it is mostly a superset of + ``'python'`` but it fallbacks to ``'none'`` without warning if failed. + ``'python3'`` and other languages will emit warning if failed. + + The value should be a valid Pygments lexer name, see + :ref:`code-examples` for more details. + + .. versionadded:: 0.5 + + .. versionchanged:: 1.4 + The default is now ``'default'``. If you prefer Python 2 only + highlighting, you can set it back to ``'python'``. + +.. confval:: highlight_options + + A dictionary that maps language names to options for the lexer modules of + Pygments. These are lexer-specific; for the options understood by each, + see the `Pygments documentation <https://pygments.org/docs/lexers>`_. + + Example:: + + highlight_options = { + 'default': {'stripall': True}, + 'php': {'startinline': True}, + } + + A single dictionary of options are also allowed. Then it is recognized + as options to the lexer specified by :confval:`highlight_language`:: + + # configuration for the ``highlight_language`` + highlight_options = {'stripall': True} + + .. versionadded:: 1.3 + .. versionchanged:: 3.5 + + Allow to configure highlight options for multiple languages + +.. confval:: pygments_style + + The style name to use for Pygments highlighting of source code. If not set, + either the theme's default style or ``'sphinx'`` is selected for HTML + output. + + .. versionchanged:: 0.3 + If the value is a fully-qualified name of a custom Pygments style class, + this is then used as custom style. + +.. confval:: maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter within the signature will be displayed on an individual logical + line. + + When ``None`` (the default), there is no maximum length and the entire + signature will be displayed on a single logical line. + + A 'logical line' is similar to a hard line break---builders or themes may + choose to 'soft wrap' a single logical line, and this setting does not affect + that behaviour. + + Domains may provide options to suppress any hard wrapping on an individual + object directive, such as seen in the C, C++, and Python domains (e.g. + :rst:dir:`py:function:single-line-parameter-list`). + + .. versionadded:: 7.1 + +.. confval:: add_function_parentheses + + A boolean that decides whether parentheses are appended to function and + method role text (e.g. the content of ``:func:`input```) to signify that the + name is callable. Default is ``True``. + +.. confval:: add_module_names + + A boolean that decides whether module names are prepended to all + :term:`object` names (for object types where a "module" of some kind is + defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``. + +.. confval:: toc_object_entries + + Create table of contents entries for domain objects (e.g. functions, classes, + attributes, etc.). Default is ``True``. + +.. confval:: toc_object_entries_show_parents + + A string that determines how domain objects (e.g. functions, classes, + attributes, etc.) are displayed in their table of contents entry. + + Use ``domain`` to allow the domain to determine the appropriate number of + parents to show. For example, the Python domain would show ``Class.method()`` + and ``function()``, leaving out the ``module.`` level of parents. + This is the default setting. + + Use ``hide`` to only show the name of the element without any parents + (i.e. ``method()``). + + Use ``all`` to show the fully-qualified name for the object + (i.e. ``module.Class.method()``), displaying all parents. + + .. versionadded:: 5.2 + +.. confval:: show_authors + + A boolean that decides whether :rst:dir:`codeauthor` and + :rst:dir:`sectionauthor` directives produce any output in the built files. + +.. confval:: modindex_common_prefix + + A list of prefixes that are ignored for sorting the Python module index + (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, + not ``F``). This can be handy if you document a project that consists of a + single package. Works only for the HTML builder currently. Default is + ``[]``. + + .. versionadded:: 0.6 + +.. confval:: trim_footnote_reference_space + + Trim spaces before footnote references that are necessary for the reST + parser to recognize the footnote, but do not look too nice in the output. + + .. versionadded:: 0.6 + +.. confval:: trim_doctest_flags + + If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at + the ends of lines and ``<BLANKLINE>`` markers are removed for all code + blocks showing interactive Python sessions (i.e. doctests). Default is + ``True``. See the extension :mod:`~sphinx.ext.doctest` for more + possibilities of including doctests. + + .. versionadded:: 1.0 + .. versionchanged:: 1.1 + Now also removes ``<BLANKLINE>``. + +.. confval:: strip_signature_backslash + + Default is ``False``. + When backslash stripping is enabled then every occurrence of ``\\`` in a + domain directive will be changed to ``\``, even within string literals. + This was the behaviour before version 3.0, and setting this variable to + ``True`` will reinstate that behaviour. + + .. versionadded:: 3.0 + +.. confval:: option_emphasise_placeholders + + Default is ``False``. + When enabled, emphasise placeholders in :rst:dir:`option` directives. + To display literal braces, escape with a backslash (``\{``). For example, + ``option_emphasise_placeholders=True`` and ``.. option:: -foption={TYPE}`` would + render with ``TYPE`` emphasised. + + .. versionadded:: 5.1 + +.. _intl-options: + +Options for internationalization +-------------------------------- + +These options influence Sphinx's *Native Language Support*. See the +documentation on :ref:`intl` for details. + +.. confval:: language + + The code for the language the docs are written in. Any text automatically + generated by Sphinx will be in that language. Also, Sphinx will try to + substitute individual paragraphs from your documents with the translation + sets obtained from :confval:`locale_dirs`. Sphinx will search + language-specific figures named by :confval:`figure_language_filename` + (e.g. the German version of ``myfigure.png`` will be ``myfigure.de.png`` + by default setting) and substitute them for original figures. In the LaTeX + builder, a suitable language will be selected as an option for the *Babel* + package. Default is ``'en'``. + + .. versionadded:: 0.5 + + .. versionchanged:: 1.4 + + Support figure substitution + + .. versionchanged:: 5.0 + + Currently supported languages by Sphinx are: + + * ``ar`` -- Arabic + * ``bg`` -- Bulgarian + * ``bn`` -- Bengali + * ``ca`` -- Catalan + * ``cak`` -- Kaqchikel + * ``cs`` -- Czech + * ``cy`` -- Welsh + * ``da`` -- Danish + * ``de`` -- German + * ``el`` -- Greek + * ``en`` -- English (default) + * ``eo`` -- Esperanto + * ``es`` -- Spanish + * ``et`` -- Estonian + * ``eu`` -- Basque + * ``fa`` -- Iranian + * ``fi`` -- Finnish + * ``fr`` -- French + * ``he`` -- Hebrew + * ``hi`` -- Hindi + * ``hi_IN`` -- Hindi (India) + * ``hr`` -- Croatian + * ``hu`` -- Hungarian + * ``id`` -- Indonesian + * ``it`` -- Italian + * ``ja`` -- Japanese + * ``ko`` -- Korean + * ``lt`` -- Lithuanian + * ``lv`` -- Latvian + * ``mk`` -- Macedonian + * ``nb_NO`` -- Norwegian Bokmal + * ``ne`` -- Nepali + * ``nl`` -- Dutch + * ``pl`` -- Polish + * ``pt`` -- Portuguese + * ``pt_BR`` -- Brazilian Portuguese + * ``pt_PT`` -- European Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``si`` -- Sinhala + * ``sk`` -- Slovak + * ``sl`` -- Slovenian + * ``sq`` -- Albanian + * ``sr`` -- Serbian + * ``sr@latin`` -- Serbian (Latin) + * ``sr_RS`` -- Serbian (Cyrillic) + * ``sv`` -- Swedish + * ``ta`` -- Tamil + * ``te`` -- Telugu + * ``tr`` -- Turkish + * ``uk_UA`` -- Ukrainian + * ``ur`` -- Urdu + * ``vi`` -- Vietnamese + * ``zh_CN`` -- Simplified Chinese + * ``zh_TW`` -- Traditional Chinese + +.. confval:: locale_dirs + + .. versionadded:: 0.5 + + Directories in which to search for additional message catalogs (see + :confval:`language`), relative to the source directory. The directories on + this path are searched by the standard :mod:`gettext` module. + + Internal messages are fetched from a text domain of ``sphinx``; so if you + add the directory :file:`./locale` to this setting, the message catalogs + (compiled from ``.po`` format using :program:`msgfmt`) must be in + :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of + individual documents depends on :confval:`gettext_compact`. + + The default is ``['locales']``. + + .. note:: The :option:`-v option for sphinx-build command <sphinx-build -v>` + is useful to check the locale_dirs config works as expected. It + emits debug messages if message catalog directory not found. + + .. versionchanged:: 1.5 + Use ``locales`` directory as a default value + +.. confval:: gettext_allow_fuzzy_translations + + If true, "fuzzy" messages in the message catalogs are used for translation. + The default is ``False``. + + .. versionadded:: 4.3 + +.. confval:: gettext_compact + + .. versionadded:: 1.1 + + If true, a document's text domain is its docname if it is a top-level + project file and its very base directory otherwise. + + If set to string, all document's text domain is this string, making all + documents use single text domain. + + By default, the document ``markup/code.rst`` ends up in the ``markup`` text + domain. With this option set to ``False``, it is ``markup/code``. + + .. versionchanged:: 3.3 + The string value is now accepted. + +.. confval:: gettext_uuid + + If true, Sphinx generates uuid information for version tracking in message + catalogs. It is used for: + + * Add uid line for each msgids in .pot files. + * Calculate similarity between new msgids and previously saved old msgids. + This calculation takes a long time. + + If you want to accelerate the calculation, you can use + ``python-levenshtein`` 3rd-party package written in C by using + :command:`pip install python-levenshtein`. + + The default is ``False``. + + .. versionadded:: 1.3 + +.. confval:: gettext_location + + If true, Sphinx generates location information for messages in message + catalogs. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_auto_build + + If true, Sphinx builds mo file for each translation catalog files. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_additional_targets + + To specify names to enable gettext extracting and translation applying for + i18n additionally. You can specify below names: + + :index: index terms + :literal-block: literal blocks (``::`` annotation and ``code-block`` directive) + :doctest-block: doctest block + :raw: raw content + :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 + + The filename format for language-specific figures. The default value is + ``{root}.{language}{ext}``. It will be expanded to + ``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``. + The available format tokens are: + + * ``{root}`` - the filename, including any path component, without the file + extension, e.g. ``dirname/filename`` + * ``{path}`` - the directory path component of the filename, with a trailing + slash if non-empty, e.g. ``dirname/`` + * ``{docpath}`` - the directory path component for the current document, with + a trailing slash if non-empty. + * ``{basename}`` - the filename without the directory path or file extension + components, e.g. ``filename`` + * ``{ext}`` - the file extension, e.g. ``.png`` + * ``{language}`` - the translation language, e.g. ``en`` + + For example, setting this to ``{path}{language}/{basename}{ext}`` will + expand to ``dirname/en/filename.png`` instead. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Added ``{path}`` and ``{basename}`` tokens. + + .. versionchanged:: 3.2 + Added ``{docpath}`` token. + +.. confval:: translation_progress_classes + + Control which, if any, classes are added to indicate translation progress. + This setting would likely only be used by translators of documentation, + in order to quickly indicate translated and untranslated content. + + * ``True``: add ``translated`` and ``untranslated`` classes + to all nodes with translatable content. + * ``translated``: only add the ``translated`` class. + * ``untranslated``: only add the ``untranslated`` class. + * ``False``: do not add any classes to indicate translation progress. + + Defaults to ``False``. + + .. versionadded:: 7.1 + +.. _math-options: + +Options for Math +---------------- + +These options influence Math notations. + +.. confval:: math_number_all + + Set this option to ``True`` if you want all displayed math to be numbered. + The default is ``False``. + +.. confval:: math_eqref_format + + A string used for formatting the labels of references to equations. + The ``{number}`` place-holder stands for the equation number. + + Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. + +.. confval:: math_numfig + + If ``True``, displayed math equations are numbered across pages when + :confval:`numfig` is enabled. The :confval:`numfig_secnum_depth` setting + is respected. The :rst:role:`eq`, not :rst:role:`numref`, role + must be used to reference equation numbers. Default is ``True``. + + .. versionadded:: 1.7 + + +.. _html-options: + +Options for HTML output +----------------------- + +These options influence HTML as well as HTML Help output, and other builders +that use Sphinx's HTMLWriter class. + +.. confval:: html_theme + + The "theme" that the HTML output should use. See the :doc:`section about + theming </usage/theming>`. The default is ``'alabaster'``. + + .. versionadded:: 0.6 + +.. confval:: html_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + .. versionadded:: 0.6 + +.. confval:: html_theme_path + + A list of paths that contain custom themes, either as subdirectories or as + zip files. Relative paths are taken as relative to the configuration + directory. + + .. versionadded:: 0.6 + +.. confval:: html_style + + The style sheet to use for HTML pages. A file of that name must exist + either in Sphinx's :file:`static/` path, or in one of the custom paths given + in :confval:`html_static_path`. Default is the stylesheet given by the + selected theme. If you only want to add or override a few things compared + to the theme's stylesheet, use CSS ``@import`` to import the theme's + stylesheet. + +.. confval:: html_title + + The "title" for HTML documentation generated with Sphinx's own templates. + This is appended to the ``<title>`` tag of individual pages, and used in the + navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} + v{<revision>} documentation'`. + +.. confval:: html_short_title + + A shorter "title" for the HTML docs. This is used for links in the + header and in the HTML Help docs. If not given, it defaults to the value of + :confval:`html_title`. + + .. versionadded:: 0.4 + +.. confval:: html_baseurl + + The base URL which points to the root of the HTML documentation. It is used + to indicate the location of document using `The Canonical Link Relation`_. + Default: ``''``. + + .. _The Canonical Link Relation: https://datatracker.ietf.org/doc/html/rfc6596 + + .. versionadded:: 1.8 + +.. confval:: html_codeblock_linenos_style + + The style of line numbers for code-blocks. + + * ``'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 + + A dictionary of values to pass into the template engine's context for all + pages. Single values can also be put in this dictionary using the + :option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``. + + .. versionadded:: 0.5 + +.. 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, 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, 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 + containing the *filename* string and the *attributes* dictionary. The + *filename* must be relative to the :confval:`html_static_path`, or a full URI + with scheme like ``https://example.org/style.css``. The *attributes* is used + for attributes of ``<link>`` tag. It defaults to an empty list. + + Example:: + + html_css_files = ['custom.css', + 'https://example.com/css/custom.css', + ('print.css', {'media': 'print'})] + + As a special attribute, *priority* can be set as an integer to load the CSS + file earlier or lazier step. For more information, refer + :meth:`.Sphinx.add_css_file()`. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + + Support priority attribute + +.. confval:: html_js_files + + A list of JavaScript *filename*. The entry must be a *filename* string or a + tuple containing the *filename* string and the *attributes* dictionary. The + *filename* must be relative to the :confval:`html_static_path`, or a full + URI with scheme like ``https://example.org/script.js``. The *attributes* is + used for attributes of ``<script>`` tag. It defaults to an empty list. + + Example:: + + html_js_files = ['script.js', + 'https://example.com/scripts/custom.js', + ('custom.js', {'async': 'async'})] + + As a special attribute, *priority* can be set as an integer to load the CSS + file earlier or lazier step. For more information, refer + :meth:`.Sphinx.add_css_file()`. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + + Support priority attribute + +.. confval:: html_static_path + + A list of paths that contain custom static files (such as style + sheets or script files). Relative paths are taken as relative to + the configuration directory. They are copied to the output's + :file:`_static` directory after the theme's static files, so a file + named :file:`default.css` will overwrite the theme's + :file:`default.css`. + + As these files are not meant to be built, they are automatically excluded + from source files. + + .. note:: + + For security reasons, dotfiles under ``html_static_path`` will + not be copied. If you would like to copy them intentionally, please + add each filepath to this setting:: + + html_static_path = ['_static', '_static/.htaccess'] + + Another way to do that, you can also use + :confval:`html_extra_path`. It allows to copy dotfiles under + the directories. + + .. versionchanged:: 0.4 + The paths in :confval:`html_static_path` can now contain subdirectories. + + .. versionchanged:: 1.0 + The entries in :confval:`html_static_path` can now be single files. + + .. versionchanged:: 1.8 + The files under :confval:`html_static_path` are excluded from source + files. + +.. confval:: html_extra_path + + A list of paths that contain extra files not directly related to + the documentation, such as :file:`robots.txt` or :file:`.htaccess`. + Relative paths are taken as relative to the configuration + directory. They are copied to the output directory. They will + overwrite any existing file of the same name. + + As these files are not meant to be built, they are automatically excluded + from source files. + + .. versionadded:: 1.2 + + .. versionchanged:: 1.4 + The dotfiles in the extra directory will be copied to the output + directory. And it refers :confval:`exclude_patterns` on copying extra + files and directories, and ignores if path matches to patterns. + +.. confval:: html_last_updated_fmt + + If this is not None, a 'Last updated on:' timestamp is inserted + at every page bottom, using the given :func:`~time.strftime` format. + The empty string is equivalent to ``'%b %d, %Y'`` (or a + locale-dependent equivalent). + +.. confval:: html_use_smartypants + + If true, quotes and dashes are converted to typographically correct + entities. Default: ``True``. + + .. deprecated:: 1.6 + To disable smart quotes, use rather :confval:`smartquotes`. + +.. confval:: html_permalinks + + Add link anchors for each heading and description environment. + Default: ``True``. + + .. versionadded:: 3.5 + +.. confval:: html_permalinks_icon + + Text for link anchors for each heading and description environment. + HTML entities and Unicode are allowed. Default: a paragraph sign; ``¶`` + + .. versionadded:: 3.5 + +.. confval:: html_sidebars + + Custom sidebar templates, must be a dictionary that maps document names to + template names. + + The keys can contain glob-style patterns [1]_, in which case all matching + documents will get the specified sidebars. (A warning is emitted when a + more than one glob-style pattern matches for any document.) + + The values can be either lists or single strings. + + * If a value is a list, it specifies the complete list of sidebar templates + to include. If all or some of the default sidebars are to be included, + they must be put into this list as well. + + The default sidebars (for documents that don't match any pattern) are + defined by theme itself. Builtin themes are using these templates by + default: ``['localtoc.html', 'relations.html', 'sourcelink.html', + 'searchbox.html']``. + + * If a value is a single string, it specifies a custom sidebar to be added + between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This + is for compatibility with Sphinx versions before 1.0. + + .. deprecated:: 1.7 + + a single string value for ``html_sidebars`` will be removed in 2.0 + + Builtin sidebar templates that can be rendered are: + + * **localtoc.html** -- a fine-grained table of contents of the current + document + * **globaltoc.html** -- a coarse-grained table of contents for the whole + documentation set, collapsed + * **relations.html** -- two links to the previous and next documents + * **sourcelink.html** -- a link to the source of the current document, if + enabled in :confval:`html_show_sourcelink` + * **searchbox.html** -- the "quick search" box + + Example:: + + html_sidebars = { + '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], + 'using/windows': ['windowssidebar.html', 'searchbox.html'], + } + + This will render the custom template ``windowssidebar.html`` and the quick + search box within the sidebar of the given document, and render the default + sidebars for all other pages (except that the local TOC is replaced by the + global TOC). + + .. versionadded:: 1.0 + The ability to use globbing keys and to specify multiple sidebars. + + Note that this value only has no effect if the chosen theme does not possess + a sidebar, like the builtin **scrolls** and **haiku** themes. + +.. confval:: html_additional_pages + + Additional templates that should be rendered to HTML pages, must be a + dictionary that maps document names to template names. + + Example:: + + html_additional_pages = { + 'download': 'customdownload.html', + } + + This will render the template ``customdownload.html`` as the page + ``download.html``. + +.. confval:: html_domain_indices + + If true, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. Default is + ``True``. + + This value can be a bool or a list of index names that should be generated. + To find out the index name for a specific index, look at the HTML file name. + For example, the Python module index has the name ``'py-modindex'``. + + .. versionadded:: 1.0 + +.. confval:: html_use_index + + If true, add an index to the HTML documents. Default is ``True``. + + .. versionadded:: 0.4 + +.. confval:: html_split_index + + If true, the index is generated twice: once as a single page with all the + entries, and once as one page per starting letter. Default is ``False``. + + .. versionadded:: 0.4 + +.. confval:: html_copy_source + + If true, the reST sources are included in the HTML build as + :file:`_sources/{name}`. The default is ``True``. + +.. confval:: html_show_sourcelink + + If true (and :confval:`html_copy_source` is true as well), links to the + reST sources will be added to the sidebar. The default is ``True``. + + .. versionadded:: 0.6 + +.. confval:: html_sourcelink_suffix + + Suffix to be appended to source links (see :confval:`html_show_sourcelink`), + unless they have this suffix already. Default is ``'.txt'``. + + .. versionadded:: 1.5 + +.. confval:: html_use_opensearch + + If nonempty, an `OpenSearch <https://github.com/dewitt/opensearch>`_ + description file will be output, and all pages will contain a ``<link>`` + tag referring to it. Since OpenSearch doesn't support relative URLs for + its search page location, the value of this option must be the base URL + from which these documents are served (without trailing slash), e.g. + ``"https://docs.python.org"``. The default is ``''``. + +.. confval:: html_file_suffix + + This is the file name suffix for generated HTML files, if set to a :obj:`str` + value. If left to the default ``None``, the suffix will be ``".html"``. + + .. versionadded:: 0.4 + +.. confval:: html_link_suffix + + Suffix for generated links to HTML files. The default is whatever + :confval:`html_file_suffix` is set to; it can be set differently (e.g. to + support different web server setups). + + .. versionadded:: 0.6 + +.. confval:: html_show_copyright + + If true, "(C) Copyright ..." is shown in the HTML footer. Default is + ``True``. + + .. versionadded:: 1.0 + +.. confval:: html_show_search_summary + + If true, the text around the keyword is shown as summary of each search result. + Default is ``True``. + + .. versionadded:: 4.5 + +.. confval:: html_show_sphinx + + If true, "Created using Sphinx" is shown in the HTML footer. Default is + ``True``. + + .. versionadded:: 0.4 + +.. confval:: html_output_encoding + + Encoding of HTML output files. Default is ``'utf-8'``. Note that this + encoding name must both be a valid Python encoding name and a valid HTML + ``charset`` value. + + .. versionadded:: 1.0 + +.. confval:: html_compact_lists + + If true, a list all whose items consist of a single paragraph and/or a + sub-list all whose items etc... (recursive definition) will not use the + ``<p>`` element for any of its items. This is standard docutils behavior. + Default: ``True``. + + .. versionadded:: 1.0 + +.. confval:: html_secnumber_suffix + + Suffix for section numbers. Default: ``". "``. Set to ``" "`` to suppress + the final dot on section numbers. + + .. versionadded:: 1.0 + +.. confval:: html_search_language + + Language to be used for generating the HTML full-text search index. This + defaults to the global language selected with :confval:`language`. If there + is no support for this language, ``"en"`` is used which selects the English + language. + + Support is present for these languages: + + * ``da`` -- Danish + * ``nl`` -- Dutch + * ``en`` -- English + * ``fi`` -- Finnish + * ``fr`` -- French + * ``de`` -- German + * ``hu`` -- Hungarian + * ``it`` -- Italian + * ``ja`` -- Japanese + * ``no`` -- Norwegian + * ``pt`` -- Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``es`` -- Spanish + * ``sv`` -- Swedish + * ``tr`` -- Turkish + * ``zh`` -- Chinese + + .. admonition:: Accelerating build speed + + Each language (except Japanese) provides its own stemming algorithm. + Sphinx uses a Python implementation by default. You can use a C + implementation to accelerate building the index file. + + * `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``) + * `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages) + + .. versionadded:: 1.1 + With support for ``en`` and ``ja``. + + .. versionchanged:: 1.3 + Added additional languages. + +.. confval:: html_search_options + + A dictionary with options for the search language support, empty by default. + The meaning of these options depends on the language selected. + + The English support has no options. + + The Japanese support has these options: + + :type: + _`type` is dotted module path string to specify Splitter implementation + which should be derived from :class:`!sphinx.search.ja.BaseSplitter`. If + not specified or ``None`` is specified, + ``'sphinx.search.ja.DefaultSplitter'`` will be used. + + You can choose from these modules: + + :'sphinx.search.ja.DefaultSplitter': + TinySegmenter algorithm. This is default splitter. + :'sphinx.search.ja.MecabSplitter': + MeCab binding. To use this splitter, 'mecab' python binding or dynamic + link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is + required. + :'sphinx.search.ja.JanomeSplitter': + Janome binding. To use this splitter, + `Janome <https://pypi.org/project/Janome/>`_ is required. + + .. deprecated:: 1.6 + ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated. + To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are + also acceptable. + + Other option values depend on splitter value which you choose. + + Options for ``'mecab'``: + :dic_enc: + _`dic_enc option` is the encoding for the MeCab algorithm. + :dict: + _`dict option` is the dictionary to use for the MeCab algorithm. + :lib: + _`lib option` is the library name for finding the MeCab library via + ctypes if the Python binding is not installed. + + For example:: + + html_search_options = { + 'type': 'mecab', + 'dic_enc': 'utf-8', + 'dict': '/path/to/mecab.dic', + 'lib': '/path/to/libmecab.so', + } + + Options for ``'janome'``: + :user_dic: + _`user_dic option` is the user dictionary file path for Janome. + :user_dic_enc: + _`user_dic_enc option` is the encoding for the user dictionary file + specified by ``user_dic`` option. Default is 'utf8'. + + .. versionadded:: 1.1 + + .. versionchanged:: 1.4 + html_search_options for Japanese is re-organized and any custom splitter + can be used by `type`_ settings. + + The Chinese support has these options: + + * ``dict`` -- the ``jieba`` dictionary path if want to use + custom dictionary. + +.. confval:: html_search_scorer + + The name of a JavaScript file (relative to the configuration directory) that + implements a search results scorer. If empty, the default will be used. + + .. XXX describe interface for scorer here + + .. versionadded:: 1.2 + +.. confval:: html_scaled_image_link + + If true, image itself links to the original image if it doesn't have + 'target' option or scale related options: 'scale', 'width', 'height'. + The default is ``True``. + + Document authors can disable this feature manually with giving + ``no-scaled-link`` class to the image: + + .. code-block:: rst + + .. image:: sphinx.png + :scale: 50% + :class: no-scaled-link + + .. versionadded:: 1.3 + + .. versionchanged:: 3.0 + + It is disabled for images having ``no-scaled-link`` class + +.. confval:: html_math_renderer + + The name of math_renderer extension for HTML output. The default is + ``'mathjax'``. + + .. versionadded:: 1.8 + +.. confval:: html_experimental_html5_writer + + Output is processed with HTML5 writer. Default is ``False``. + + .. versionadded:: 1.6 + + .. deprecated:: 2.0 + +.. confval:: html4_writer + + Output is processed with HTML4 writer. Default is ``False``. + +Options for Single HTML output +------------------------------- + +.. confval:: singlehtml_sidebars + + Custom sidebar templates, must be a dictionary that maps document names to + template names. And it only allows a key named `'index'`. All other keys + are ignored. For more information, refer to :confval:`html_sidebars`. By + default, it is same as :confval:`html_sidebars`. + + +.. _htmlhelp-options: + +Options for HTML help output +----------------------------- + +.. confval:: htmlhelp_basename + + Output file base name for HTML help builder. Default is ``'pydoc'``. + +.. confval:: htmlhelp_file_suffix + + This is the file name suffix for generated HTML help files. The + default is ``".html"``. + + .. versionadded:: 2.0 + +.. confval:: htmlhelp_link_suffix + + Suffix for generated links to HTML files. The default is ``".html"``. + + .. versionadded:: 2.0 + + +.. _applehelp-options: + +Options for Apple Help output +----------------------------- + +.. versionadded:: 1.3 + +These options influence the Apple Help output. This builder derives from the +HTML builder, so the HTML options also apply where appropriate. + +.. note:: + + Apple Help output will only work on Mac OS X 10.6 and higher, as it + requires the :program:`hiutil` and :program:`codesign` command line tools, + neither of which are Open Source. + + You can disable the use of these tools using + :confval:`applehelp_disable_external_tools`, but the result will not be a + valid help book until the indexer is run over the ``.lproj`` folders within + the bundle. + +.. confval:: applehelp_bundle_name + + The basename for the Apple Help Book. Defaults to the :confval:`project` + name. + +.. confval:: applehelp_bundle_id + + The bundle ID for the help book bundle. + + .. warning:: + + You *must* set this value in order to generate Apple Help. + +.. confval:: applehelp_dev_region + + The development region. Defaults to ``'en-us'``, which is Apple’s + recommended setting. + +.. confval:: applehelp_bundle_version + + The bundle version (as a string). Defaults to ``'1'``. + +.. confval:: applehelp_icon + + The help bundle icon file, or ``None`` for no icon. According to Apple's + documentation, this should be a 16-by-16 pixel version of the application's + icon with a transparent background, saved as a PNG file. + +.. confval:: applehelp_kb_product + + The product tag for use with :confval:`applehelp_kb_url`. Defaults to + :samp:`'{<project>}-{<release>}'`. + +.. confval:: applehelp_kb_url + + The URL for your knowledgebase server, + e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``. + Help Viewer will replace the values ``'product'``, ``'query'`` and + ``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`, + the text entered by the user in the search box and the user's system + language respectively. + + Defaults to ``None`` for no remote search. + +.. confval:: applehelp_remote_url + + The URL for remote content. You can place a copy of your Help Book's + ``Resources`` folder at this location and Help Viewer will attempt to use + it to fetch updated content. + + e.g. if you set it to ``https://example.com/help/Foo/`` and Help Viewer + wants a copy of ``index.html`` for an English speaking customer, it will + look at ``https://example.com/help/Foo/en.lproj/index.html``. + + Defaults to ``None`` for no remote content. + +.. confval:: applehelp_index_anchors + + If ``True``, tell the help indexer to index anchors in the generated HTML. + This can be useful for jumping to a particular topic using the + ``AHLookupAnchor`` function or the ``openHelpAnchor:inBook:`` method in + your code. It also allows you to use ``help:anchor`` URLs; see the Apple + documentation for more information on this topic. + +.. confval:: applehelp_min_term_length + + Controls the minimum term length for the help indexer. Defaults to + ``None``, which means the default will be used. + +.. confval:: applehelp_stopwords + + Either a language specification (to use the built-in stopwords), or the + path to a stopwords plist, or ``None`` if you do not want to use stopwords. + The default stopwords plist can be found at + ``/usr/share/hiutil/Stopwords.plist`` and contains, at time of writing, + stopwords for the following languages: + + ========= ==== + Language Code + ========= ==== + English en + German de + Spanish es + French fr + Swedish sv + Hungarian hu + Italian it + ========= ==== + + Defaults to :confval:`language`, or if that is not set, to ``'en'``. + +.. confval:: applehelp_locale + + Specifies the locale to generate help for. This is used to determine + the name of the ``.lproj`` folder inside the Help Book’s ``Resources``, and + is passed to the help indexer. + + Defaults to :confval:`language`, or if that is not set, to ``'en'``. + +.. confval:: applehelp_title + + Specifies the help book title. Defaults to :samp:`'{<project>} Help'`. + +.. confval:: applehelp_codesign_identity + + Specifies the identity to use for code signing, or ``None`` if code signing + is not to be performed. + + Defaults to the value of the environment variable ``CODE_SIGN_IDENTITY``, + which is set by Xcode for script build phases, or ``None`` if that variable + is not set. + +.. confval:: applehelp_codesign_flags + + A *list* of additional arguments to pass to :program:`codesign` when + signing the help book. + + Defaults to a list based on the value of the environment variable + ``OTHER_CODE_SIGN_FLAGS``, which is set by Xcode for script build phases, + or the empty list if that variable is not set. + +.. confval:: applehelp_indexer_path + + The path to the :program:`hiutil` program. Defaults to + ``'/usr/bin/hiutil'``. + +.. confval:: applehelp_codesign_path + + The path to the :program:`codesign` program. Defaults to + ``'/usr/bin/codesign'``. + +.. confval:: applehelp_disable_external_tools + + If ``True``, the builder will not run the indexer or the code signing tool, + no matter what other settings are specified. + + This is mainly useful for testing, or where you want to run the Sphinx + build on a non-Mac OS X platform and then complete the final steps on OS X + for some reason. + + Defaults to ``False``. + + +.. _epub-options: + +Options for epub output +----------------------- + +These options influence the epub output. As this builder derives from the HTML +builder, the HTML options also apply where appropriate. The actual values for +some of the options is not really important, they just have to be entered into +the `Dublin Core metadata <https://dublincore.org/>`_. + +.. confval:: epub_basename + + The basename for the epub file. It defaults to the :confval:`project` name. + +.. confval:: epub_theme + + The HTML theme for the epub output. Since the default themes are not + optimized for small screen space, using the same theme for HTML and epub + output is usually not wise. This defaults to ``'epub'``, a theme designed + to save visual space. + +.. confval:: epub_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + .. versionadded:: 1.2 + +.. confval:: epub_title + + The title of the document. It defaults to the :confval:`html_title` option + but can be set independently for epub creation. It defaults to the + :confval:`project` option. + + .. versionchanged:: 2.0 + It defaults to the ``project`` option. + +.. confval:: epub_description + + The description of the document. The default value is ``'unknown'``. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Renamed from ``epub3_description`` + +.. confval:: epub_author + + The author of the document. This is put in the Dublin Core metadata. It + defaults to the :confval:`author` option. + +.. confval:: epub_contributor + + The name of a person, organization, etc. that played a secondary role in + the creation of the content of an EPUB Publication. The default value is + ``'unknown'``. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Renamed from ``epub3_contributor`` + +.. confval:: epub_language + + The language of the document. This is put in the Dublin Core metadata. The + default is the :confval:`language` option or ``'en'`` if unset. + +.. confval:: epub_publisher + + The publisher of the document. This is put in the Dublin Core metadata. + You may use any sensible string, e.g. the project homepage. The defaults to + the :confval:`author` option. + +.. confval:: epub_copyright + + The copyright of the document. It defaults to the :confval:`copyright` + option but can be set independently for epub creation. + +.. confval:: epub_identifier + + An identifier for the document. This is put in the Dublin Core metadata. + For published documents this is the ISBN number, but you can also use an + alternative scheme, e.g. the project homepage. The default value is + ``'unknown'``. + +.. confval:: epub_scheme + + The publication scheme for the :confval:`epub_identifier`. This is put in + the Dublin Core metadata. For published books the scheme is ``'ISBN'``. If + you use the project homepage, ``'URL'`` seems reasonable. The default value + is ``'unknown'``. + +.. confval:: epub_uid + + A unique identifier for the document. This is put in the Dublin Core + metadata. You may use a + `XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_ + string. You can't use hyphen, period, numbers as a first character. The + default value is ``'unknown'``. + +.. confval:: epub_cover + + The cover page information. This is a tuple containing the filenames of + the cover image and the html template. The rendered html cover page is + inserted as the first item in the spine in :file:`content.opf`. If the + template filename is empty, no html cover page is created. No cover at all + is created if the tuple is empty. Examples:: + + epub_cover = ('_static/cover.png', 'epub-cover.html') + epub_cover = ('_static/cover.png', '') + epub_cover = () + + The default value is ``()``. + + .. versionadded:: 1.1 + +.. confval:: epub_css_files + + A list of CSS files. The entry must be a *filename* string or a tuple + containing the *filename* string and the *attributes* dictionary. For more + information, see :confval:`html_css_files`. + + .. versionadded:: 1.8 + +.. confval:: epub_guide + + Meta data for the guide element of :file:`content.opf`. This is a + sequence of tuples containing the *type*, the *uri* and the *title* of + the optional guide information. See the OPF documentation + at `<http://idpf.org/epub>`_ for details. If possible, default entries + for the *cover* and *toc* types are automatically inserted. However, + the types can be explicitly overwritten if the default entries are not + appropriate. Example:: + + epub_guide = (('cover', 'cover.html', 'Cover Page'),) + + The default value is ``()``. + +.. confval:: epub_pre_files + + Additional files that should be inserted before the text generated by + Sphinx. It is a list of tuples containing the file name and the title. + If the title is empty, no entry is added to :file:`toc.ncx`. Example:: + + epub_pre_files = [ + ('index.html', 'Welcome'), + ] + + The default value is ``[]``. + +.. confval:: epub_post_files + + Additional files that should be inserted after the text generated by Sphinx. + It is a list of tuples containing the file name and the title. This option + can be used to add an appendix. If the title is empty, no entry is added + to :file:`toc.ncx`. The default value is ``[]``. + +.. confval:: epub_exclude_files + + A list of files that are generated/copied in the build directory but should + not be included in the epub file. The default value is ``[]``. + +.. confval:: epub_tocdepth + + The depth of the table of contents in the file :file:`toc.ncx`. It should + be an integer greater than zero. The default value is 3. Note: A deeply + nested table of contents may be difficult to navigate. + +.. confval:: epub_tocdup + + This flag determines if a toc entry is inserted again at the beginning of + its nested toc listing. This allows easier navigation to the top of + a chapter, but can be confusing because it mixes entries of different + depth in one list. The default value is ``True``. + +.. confval:: epub_tocscope + + This setting control the scope of the epub table of contents. The setting + can have the following values: + + * ``'default'`` -- include all toc entries that are not hidden (default) + * ``'includehidden'`` -- include all toc entries + + .. versionadded:: 1.2 + +.. confval:: epub_fix_images + + This flag determines if sphinx should try to fix image formats that are not + supported by some epub readers. At the moment palette images with a small + color table are upgraded. You need Pillow, the Python Image Library, + installed to use this option. The default value is ``False`` because the + automatic conversion may lose information. + + .. versionadded:: 1.2 + +.. confval:: epub_max_image_width + + This option specifies the maximum width of images. If it is set to a value + greater than zero, images with a width larger than the given value are + scaled accordingly. If it is zero, no scaling is performed. The default + value is ``0``. You need the Python Image Library (Pillow) installed to use + this option. + + .. versionadded:: 1.2 + +.. confval:: epub_show_urls + + Control whether to display URL addresses. This is very useful for + readers that have no other means to display the linked URL. The + settings can have the following values: + + * ``'inline'`` -- display URLs inline in parentheses (default) + * ``'footnote'`` -- display URLs in footnotes + * ``'no'`` -- do not display URLs + + The display of inline URLs can be customized by adding CSS rules for the + class ``link-target``. + + .. versionadded:: 1.2 + +.. confval:: epub_use_index + + If true, add an index to the epub document. It defaults to the + :confval:`html_use_index` option but can be set independently for epub + creation. + + .. versionadded:: 1.2 + +.. confval:: epub_writing_mode + + It specifies writing direction. It can accept ``'horizontal'`` (default) and + ``'vertical'`` + + .. list-table:: + :header-rows: 1 + :stub-columns: 1 + + - * ``epub_writing_mode`` + * ``'horizontal'`` + * ``'vertical'`` + - * writing-mode [#]_ + * ``horizontal-tb`` + * ``vertical-rl`` + - * page progression + * left to right + * right to left + - * iBook's Scroll Theme support + * scroll-axis is vertical. + * scroll-axis is horizontal. + + .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode + + +.. _latex-options: + +Options for LaTeX output +------------------------ + +These options influence LaTeX output. + +.. confval:: latex_engine + + The LaTeX engine to build the docs. The setting can have the following + values: + + * ``'pdflatex'`` -- PDFLaTeX (default) + * ``'xelatex'`` -- XeLaTeX + * ``'lualatex'`` -- LuaLaTeX + * ``'platex'`` -- pLaTeX + * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``) + + ``'pdflatex'``\ 's support for Unicode characters is limited. + + .. note:: + + 2.0 adds to ``'pdflatex'`` support in Latin language document of + occasional Cyrillic or Greek letters or words. This is not automatic, + see the discussion of the :confval:`latex_elements` ``'fontenc'`` key. + + If your project uses Unicode characters, setting the engine to + ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font + with wide-enough glyph coverage is often easier than trying to make + ``'pdflatex'`` work with the extra Unicode characters. Since Sphinx 2.0 + the default is the GNU FreeFont which covers well Latin, Cyrillic and + Greek. + + .. versionchanged:: 2.1.0 + + Use ``xelatex`` (and LaTeX package ``xeCJK``) by default for Chinese + documents. + + .. versionchanged:: 2.2.1 + + Use ``xelatex`` by default for Greek documents. + + .. versionchanged:: 2.3 + + 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 + use ``'xelatex'`` or ``'lualatex'`` *and* to add + ``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements` + ``'preamble'`` key). You may prefer + ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode + literal such as ``α`` (U+03B1) for example as is in output, rather than + being rendered as :math:`\alpha`. + +.. confval:: latex_documents + + This value determines how to group the document tree into LaTeX source files. + It must be a list of tuples ``(startdocname, targetname, title, author, + theme, toctree_only)``, where the items are: + + *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 root + document for your LaTeX build, provide your :confval:`root_doc` here.) + + *targetname* + File name of the LaTeX file in the output directory. + + *title* + LaTeX document title. Can be empty to use the title of the *startdoc* + document. This is inserted as LaTeX markup, so special characters like a + backslash or ampersand must be represented by the proper LaTeX commands if + they are to be inserted literally. + + *author* + Author for the LaTeX document. The same LaTeX markup caveat as for *title* + applies. Use ``\\and`` to separate multiple authors, as in: + ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX). + + *theme* + LaTeX theme. See :confval:`latex_theme`. + + *toctree_only* + Must be ``True`` or ``False``. If true, the *startdoc* document itself is + not included in the output, only the documents referenced by it via TOC + trees. With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the LaTeX output. + + .. versionadded:: 1.2 + In the past including your own document class required you to prepend the + document class name with the string "sphinx". This is not necessary + anymore. + + .. versionadded:: 0.3 + The 6th item ``toctree_only``. Tuples with 5 items are still accepted. + +.. confval:: latex_logo + + If given, this must be the name of an image file (relative to the + configuration directory) that is the logo of the docs. It is placed at the + top of the title page. Default: ``None``. + +.. confval:: latex_toplevel_sectioning + + This value determines the topmost sectioning unit. It should be chosen from + ``'part'``, ``'chapter'`` or ``'section'``. The default is ``None``; + the topmost + sectioning unit is switched by documentclass: ``section`` is used if + documentclass will be ``howto``, otherwise ``chapter`` will be used. + + Note that if LaTeX uses ``\part`` command, then the numbering of sectioning + units one level deep gets off-sync with HTML numbering, because LaTeX + numbers continuously ``\chapter`` (or ``\section`` for ``howto``.) + + .. versionadded:: 1.4 + +.. confval:: latex_appendices + + A list of document names to append as an appendix to all manuals. + +.. confval:: latex_domain_indices + + If true, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. Default is + ``True``. + + This value can be a bool or a list of index names that should be generated, + like for :confval:`html_domain_indices`. + + .. versionadded:: 1.0 + +.. confval:: latex_show_pagerefs + + If true, add page references after internal references. This is very useful + for printed copies of the manual. Default is ``False``. + + .. versionadded:: 1.0 + +.. confval:: latex_show_urls + + Control whether to display URL addresses. This is very useful for printed + copies of the manual. The setting can have the following values: + + * ``'no'`` -- do not display URLs (default) + * ``'footnote'`` -- display URLs in footnotes + * ``'inline'`` -- display URLs inline in parentheses + + .. versionadded:: 1.0 + .. versionchanged:: 1.1 + This value is now a string; previously it was a boolean value, and a true + value selected the ``'inline'`` display. For backwards compatibility, + ``True`` is still accepted. + +.. confval:: latex_use_latex_multicolumn + + The default is ``False``: it means that Sphinx's own macros are used for + merged cells from grid tables. They allow general contents (literal blocks, + lists, blockquotes, ...) but may have problems if the + :rst:dir:`tabularcolumns` directive was used to inject LaTeX mark-up of the + type ``>{..}``, ``<{..}``, ``@{..}`` as column specification. + + Setting to ``True`` means to use LaTeX's standard ``\multicolumn``; this is + incompatible with literal blocks in the horizontally merged cell, and also + with multiple paragraphs in such cell if the table is rendered using + ``tabulary``. + + .. versionadded:: 1.6 + +.. confval:: latex_table_style + + A list of styling classes (strings). Currently supported: + + - ``'booktabs'``: no vertical lines, and only 2 or 3 horizontal lines (the + latter if there is a header), using the booktabs_ package. + + - ``'borderless'``: no lines whatsoever. + + - ``'colorrows'``: the table rows are rendered with alternating background + colours. The interface to customize them is via :ref:`dedicated keys + <tablecolors>` of :ref:`latexsphinxsetup`. + + .. important:: + + With the ``'colorrows'`` style, the ``\rowcolors`` LaTeX command + becomes a no-op (this command has limitations and has never correctly + supported all types of tables Sphinx produces in LaTeX). Please + update your project to use instead + the :ref:`latex table color configuration <tablecolors>` keys. + + Default: ``['booktabs', 'colorrows']`` + + .. versionadded:: 5.3.0 + + .. versionchanged:: 6.0.0 + + Modify default from ``[]`` to ``['booktabs', 'colorrows']``. + + Each table can override the global style via ``:class:`` option, or + ``.. rst-class::`` for no-directive tables (cf. :ref:`table-directives`). + Currently recognized classes are ``booktabs``, ``borderless``, + ``standard``, ``colorrows``, ``nocolorrows``. The latter two can be + combined with any of the first three. The ``standard`` class produces + tables with both horizontal and vertical lines (as has been the default so + far with Sphinx). + + A single-row multi-column merged cell will obey the row colour, if it is + set. See also ``TableMergeColor{Header,Odd,Even}`` in the + :ref:`latexsphinxsetup` section. + + .. note:: + + - It is hard-coded in LaTeX that a single cell will obey the row colour + even if there is a column colour set via ``\columncolor`` from a + column specification (see :rst:dir:`tabularcolumns`). Sphinx provides + ``\sphinxnorowcolor`` which can be used like this: + + .. code-block:: latex + + >{\columncolor{blue}\sphinxnorowcolor} + + in a table column specification. + + - Sphinx also provides ``\sphinxcolorblend`` which however requires the + xcolor_ package. Here is an example: + + .. code-block:: latex + + >{\sphinxcolorblend{!95!red}} + + It means that in this column, the row colours will be slightly tinted + by red; refer to xcolor_ documentation for more on the syntax of its + ``\blendcolors`` command (a ``\blendcolors`` in place of + ``\sphinxcolorblend`` would modify colours of the cell *contents*, not + of the cell *background colour panel*...). You can find an example of + usage in the :ref:`dev-deprecated-apis` section of this document in + PDF format. + + .. hint:: + + If you want to use a special colour for the *contents* of the + cells of a given column use ``>{\noindent\color{<color>}}``, + possibly in addition to the above. + + - Multi-row merged cells, whether single column or multi-column + currently ignore any set column, row, or cell colour. + + - It is possible for a simple cell to set a custom colour via the + :dudir:`raw` directive and the ``\cellcolor`` LaTeX command used + anywhere in the cell contents. This currently is without effect + in a merged cell, whatever its kind. + + .. hint:: + + In a document not using ``'booktabs'`` globally, it is possible to style + an individual table via the ``booktabs`` class, but it will be necessary + to add ``r'\usepackage{booktabs}'`` to the LaTeX preamble. + + On the other hand one can use ``colorrows`` class for individual tables + with no extra package (as Sphinx since 5.3.0 always loads colortbl_). + + .. _booktabs: https://ctan.org/pkg/booktabs + .. _colortbl: https://ctan.org/pkg/colortbl + .. _xcolor: https://ctan.org/pkg/xcolor + +.. confval:: latex_use_xindy + + If ``True``, the PDF build from the LaTeX files created by Sphinx + will use :program:`xindy` (doc__) rather than :program:`makeindex` + for preparing the index of general terms (from :rst:dir:`index` + usage). This means that words with UTF-8 characters will get + ordered correctly for the :confval:`language`. + + __ http://xindy.sourceforge.net/ + + - This option is ignored if :confval:`latex_engine` is ``'platex'`` + (Japanese documents; :program:`mendex` replaces :program:`makeindex` + then). + + - The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as + :program:`makeindex`, if any indexed term starts with a non-ascii + character, creates ``.ind`` files containing invalid bytes for + UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF + build. + + - The default is ``False`` for ``'pdflatex'`` but ``True`` is + recommended for non-English documents as soon as some indexed + terms use non-ascii characters from the language script. + + Sphinx adds to :program:`xindy` base distribution some dedicated support + for using ``'pdflatex'`` engine with Cyrillic scripts. And whether with + ``'pdflatex'`` or Unicode engines, Cyrillic documents handle correctly the + indexing of Latin names, even with diacritics. + + .. versionadded:: 1.8 + +.. confval:: latex_elements + + .. versionadded:: 0.5 + + Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`. + +.. confval:: latex_docclass + + A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document + classes that will be used as the base for the two Sphinx classes. Default + is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``. + + .. versionadded:: 1.0 + + .. versionchanged:: 1.5 + + In Japanese docs (:confval:`language` is ``'ja'``), by default + ``'jreport'`` is used for ``'howto'`` and ``'jsbook'`` for ``'manual'``. + +.. confval:: latex_additional_files + + A list of file names, relative to the configuration directory, to copy to + the build directory when building LaTeX output. This is useful to copy + files that Sphinx doesn't copy automatically, e.g. if they are referenced in + custom LaTeX added in ``latex_elements``. Image files that are referenced + in source files (e.g. via ``.. image::``) are copied automatically. + + You have to make sure yourself that the filenames don't collide with those + of any automatically copied files. + + .. attention:: + + Filenames with extension ``.tex`` will automatically be handed over to + the PDF build process triggered by :option:`sphinx-build -M` + ``latexpdf`` or by :program:`make latexpdf`. If the file was added only + to be ``\input{}`` from a modified preamble, you must add a further + suffix such as ``.txt`` to the filename and adjust accordingly the + ``\input{}`` command added to the LaTeX document preamble. + + .. versionadded:: 0.6 + + .. versionchanged:: 1.2 + This overrides the files which is provided from Sphinx such as + ``sphinx.sty``. + +.. confval:: latex_theme + + The "theme" that the LaTeX output should use. It is a collection of settings + for LaTeX output (ex. document class, top level sectioning unit and so on). + + As a built-in LaTeX themes, ``manual`` and ``howto`` are bundled. + + ``manual`` + A LaTeX theme for writing a manual. It imports the ``report`` document + class (Japanese documents use ``jsbook``). + + ``howto`` + A LaTeX theme for writing an article. It imports the ``article`` document + class (Japanese documents use ``jreport`` rather). :confval:`latex_appendices` + is available only for this theme. + + It defaults to ``'manual'``. + + .. versionadded:: 3.0 + +.. confval:: latex_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. + + .. versionadded:: 3.1 + +.. confval:: latex_theme_path + + A list of paths that contain custom LaTeX themes as subdirectories. Relative + paths are taken as relative to the configuration directory. + + .. versionadded:: 3.0 + + +.. _text-options: + +Options for text output +----------------------- + +These options influence text output. + +.. confval:: text_newlines + + Determines which end-of-line character(s) are used in text output. + + * ``'unix'``: use Unix-style line endings (``\n``) + * ``'windows'``: use Windows-style line endings (``\r\n``) + * ``'native'``: use the line ending style of the platform the documentation + is built on + + Default: ``'unix'``. + + .. versionadded:: 1.1 + +.. confval:: text_sectionchars + + A string of 7 characters that should be used for underlining sections. + The first character is used for first-level headings, the second for + second-level headings and so on. + + The default is ``'*=-~"+`'``. + + .. versionadded:: 1.1 + +.. confval:: text_add_secnumbers + + A boolean that decides whether section numbers are included in text output. + Default is ``True``. + + .. versionadded:: 1.7 + +.. confval:: text_secnumber_suffix + + Suffix for section numbers in text output. Default: ``". "``. Set to + ``" "`` to suppress the final dot on section numbers. + + .. versionadded:: 1.7 + + +.. _man-options: + +Options for manual page output +------------------------------ + +These options influence manual page output. + +.. confval:: man_pages + + This value determines how to group the document tree into manual pages. It + must be a list of tuples ``(startdocname, name, description, authors, + section)``, where the items are: + + *startdocname* + 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 + root document for your manual pages build, use your :confval:`root_doc` + here.) + + *name* + Name of the manual page. This should be a short string without spaces or + special characters. It is used to determine the file name as well as the + name of the manual page (in the NAME section). + + *description* + Description of the manual page. This is used in the NAME section. + Can be an empty string if you do not want to automatically generate + the NAME section. + + *authors* + A list of strings with authors, or a single string. Can be an empty + string or list if you do not want to automatically generate an AUTHORS + section in the manual page. + + *section* + The manual page section. Used for the output file name as well as in the + manual page header. + + .. versionadded:: 1.0 + +.. confval:: man_show_urls + + If true, add URL addresses after links. Default is ``False``. + + .. versionadded:: 1.1 + +.. confval:: man_make_section_directory + + 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``. + + .. versionchanged:: 4.0.2 + + The default is changed to ``True`` from ``False`` again. + +.. _texinfo-options: + +Options for Texinfo output +-------------------------- + +These options influence Texinfo output. + +.. confval:: texinfo_documents + + This value determines how to group the document tree into Texinfo source + files. It must be a list of tuples ``(startdocname, targetname, title, + author, dir_entry, description, category, toctree_only)``, where the items + are: + + *startdocname* + String that specifies the :term:`document name` of the the Texinfo file's + 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:`root_doc` here.) + + *targetname* + File name (no extension) of the Texinfo file in the output directory. + + *title* + Texinfo document title. Can be empty to use the title of the *startdoc* + document. Inserted as Texinfo markup, so special characters like ``@`` and + ``{}`` will need to be escaped to be inserted literally. + + *author* + Author for the Texinfo document. Inserted as Texinfo markup. Use ``@*`` + to separate multiple authors, as in: ``'John@*Sarah'``. + + *dir_entry* + The name that will appear in the top-level ``DIR`` menu file. + + *description* + Descriptive text to appear in the top-level ``DIR`` menu file. + + *category* + Specifies the section which this entry will appear in the top-level + ``DIR`` menu file. + + *toctree_only* + Must be ``True`` or ``False``. If true, the *startdoc* document itself is + not included in the output, only the documents referenced by it via TOC + trees. With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the Texinfo output. + + .. versionadded:: 1.1 + +.. confval:: texinfo_appendices + + A list of document names to append as an appendix to all manuals. + + .. versionadded:: 1.1 + +.. confval:: texinfo_domain_indices + + If true, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. Default is + ``True``. + + This value can be a bool or a list of index names that should be generated, + like for :confval:`html_domain_indices`. + + .. versionadded:: 1.1 + +.. confval:: texinfo_show_urls + + Control how to display URL addresses. + + * ``'footnote'`` -- display URLs in footnotes (default) + * ``'no'`` -- do not display URLs + * ``'inline'`` -- display URLs inline in parentheses + + .. versionadded:: 1.1 + +.. confval:: texinfo_no_detailmenu + + If true, do not generate a ``@detailmenu`` in the "Top" node's menu + containing entries for each sub-node in the document. Default is ``False``. + + .. versionadded:: 1.2 + +.. confval:: texinfo_elements + + A dictionary that contains Texinfo snippets that override those Sphinx + usually puts into the generated ``.texi`` files. + + * Keys that you may want to override include: + + ``'paragraphindent'`` + Number of spaces to indent the first line of each paragraph, default + ``2``. Specify ``0`` for no indentation. + + ``'exampleindent'`` + Number of spaces to indent the lines for examples or literal blocks, + default ``4``. Specify ``0`` for no indentation. + + ``'preamble'`` + Texinfo markup inserted near the beginning of the file. + + ``'copying'`` + Texinfo markup inserted within the ``@copying`` block and displayed + after the title. The default value consists of a simple title page + identifying the project. + + * Keys that are set by other options and therefore should not be overridden + are: + + ``'author'`` + ``'body'`` + ``'date'`` + ``'direntry'`` + ``'filename'`` + ``'project'`` + ``'release'`` + ``'title'`` + + .. versionadded:: 1.1 + +.. confval:: texinfo_cross_references + + If false, do not generate inline references in a document. That makes + an info file more readable with stand-alone reader (``info``). + Default is ``True``. + + .. versionadded:: 4.4 + +.. _qthelp-options: + +Options for QtHelp output +-------------------------- + +These options influence qthelp output. As this builder derives from the HTML +builder, the HTML options also apply where appropriate. + +.. confval:: qthelp_basename + + The basename for the qthelp file. It defaults to the :confval:`project` + name. + +.. confval:: qthelp_namespace + + The namespace for the qthelp file. It defaults to + ``org.sphinx.<project_name>.<project_version>``. + +.. confval:: qthelp_theme + + The HTML theme for the qthelp output. + This defaults to ``'nonav'``. + +.. confval:: qthelp_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + +Options for the linkcheck builder +--------------------------------- + +.. confval:: linkcheck_ignore + + A list of regular expressions that match URIs that should not be checked + when doing a ``linkcheck`` build. Example:: + + linkcheck_ignore = [r'http://localhost:\d+/'] + + .. versionadded:: 1.1 + +.. confval:: linkcheck_allowed_redirects + + A dictionary that maps a pattern of the source URI to a pattern of the canonical + URI. The linkcheck builder treats the redirected link as "working" when: + + - the link in the document matches the source URI pattern, and + - the redirect location matches the canonical URI pattern. + + Example: + + .. code-block:: python + + linkcheck_allowed_redirects = { + # All HTTP redirections from the source URI to the canonical URI will be treated as "working". + r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' + } + + If set, linkcheck builder will emit a warning when disallowed redirection + found. It's useful to detect unexpected redirects under :option:`the + warn-is-error mode <sphinx-build -W>`. + + .. versionadded:: 4.1 + +.. confval:: linkcheck_request_headers + + A dictionary that maps baseurls to HTTP request headers. + + The key is a URL base string like ``"https://www.sphinx-doc.org/"``. To specify + headers for other hosts, ``"*"`` can be used. It matches all hosts only when + the URL does not match other settings. + + The value is a dictionary that maps header name to its value. + + Example: + + .. code-block:: python + + linkcheck_request_headers = { + "https://www.sphinx-doc.org/": { + "Accept": "text/html", + "Accept-Encoding": "utf-8", + }, + "*": { + "Accept": "text/html,application/xhtml+xml", + } + } + + .. versionadded:: 3.1 + +.. confval:: linkcheck_retries + + The number of times the linkcheck builder will attempt to check a URL before + declaring it broken. Defaults to 1 attempt. + + .. versionadded:: 1.4 + +.. confval:: linkcheck_timeout + + A timeout value, in seconds, for the linkcheck builder. The default is to + use Python's global socket timeout. + + .. versionadded:: 1.1 + +.. confval:: linkcheck_workers + + The number of worker threads to use when checking links. Default is 5 + threads. + + .. versionadded:: 1.1 + +.. confval:: linkcheck_anchors + + If true, check the validity of ``#anchor``\ s in links. Since this requires + downloading the whole document, it's considerably slower when enabled. + Default is ``True``. + + .. versionadded:: 1.2 + +.. confval:: linkcheck_anchors_ignore + + A list of regular expressions that match anchors Sphinx should skip when + checking the validity of anchors in links. This allows skipping anchors that + a website's JavaScript adds to control dynamic pages or when triggering an + internal REST request. Default is ``["^!"]``. + + .. tip:: + + Use :confval:`linkcheck_anchors_ignore_for_url` to check a URL, + but skip verifying that the anchors exist. + + .. note:: + + If you want to ignore anchors of a specific page or of pages that match a + specific pattern (but still check occurrences of the same page(s) that + don't have anchors), use :confval:`linkcheck_ignore` instead, for example + as follows:: + + linkcheck_ignore = [ + 'https://www.sphinx-doc.org/en/1.7/intro.html#', + ] + + .. versionadded:: 1.5 + +.. confval:: linkcheck_anchors_ignore_for_url + + A list or tuple of regular expressions matching URLs + for which Sphinx should not check the validity of anchors. + This allows skipping anchor checks on a per-page basis + while still checking the validity of the page itself. + Default is an empty tuple ``()``. + + .. versionadded:: 7.1 + +.. confval:: linkcheck_auth + + Pass authentication information when doing a ``linkcheck`` build. + + A list of ``(regex_pattern, auth_info)`` tuples where the items are: + + *regex_pattern* + A regular expression that matches a URI. + *auth_info* + Authentication information to use for that URI. The value can be anything + that is understood by the ``requests`` library (see :ref:`requests + Authentication <requests:authentication>` for details). + + The ``linkcheck`` builder will use the first matching ``auth_info`` value + it can find in the :confval:`linkcheck_auth` list, so values earlier in the + list have higher priority. + + Example:: + + linkcheck_auth = [ + ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')), + ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)), + ] + + .. versionadded:: 2.3 + +.. confval:: linkcheck_rate_limit_timeout + + The ``linkcheck`` builder may issue a large number of requests to the same + site over a short period of time. This setting controls the builder behavior + when servers indicate that requests are rate-limited. + + If a server indicates when to retry (using the `Retry-After`_ header), + ``linkcheck`` always follows the server indication. + + Otherwise, ``linkcheck`` waits for a minute before to retry and keeps + doubling the wait time between attempts until it succeeds or exceeds the + ``linkcheck_rate_limit_timeout``. By default, the timeout is 5 minutes. + + .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3 + + .. versionadded:: 3.4 + +.. confval:: linkcheck_exclude_documents + + A list of regular expressions that match documents in which Sphinx should + not check the validity of links. This can be used for permitting link decay + in legacy or historical sections of the documentation. + + Example:: + + # ignore all links in documents located in a subfolder named 'legacy' + linkcheck_exclude_documents = [r'.*/legacy/.*'] + + .. versionadded:: 4.4 + + +Options for the XML builder +--------------------------- + +.. confval:: xml_pretty + + If true, pretty-print the XML. Default is ``True``. + + .. versionadded:: 1.2 + + +.. rubric:: Footnotes + +.. [1] A note on available globbing syntax: you can use the standard shell + constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that + these all don't match slashes. A double star ``**`` can be used to + match any sequence of characters *including* slashes. + + +.. _c-config: + +Options for the C domain +------------------------ + +.. confval:: c_id_attributes + + A list of strings that the parser additionally should accept as attributes. + This can for example be used when attributes have been ``#define`` d for + portability. + + .. versionadded:: 3.0 + +.. confval:: c_paren_attributes + + A list of strings that the parser additionally should accept as attributes + with one argument. That is, if ``my_align_as`` is in the list, then + ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have + balanced braces (``()``, ``[]``, and ``{}``). This can for example be used + when attributes have been ``#define`` d for portability. + + .. versionadded:: 3.0 + +.. confval:: c_extra_keywords + + A list of identifiers to be recognized as keywords by the C parser. + It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary', + 'noreturn', 'static_assert', 'thread_local']``. + + .. versionadded:: 4.0.3 + +.. confval:: c_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter will be displayed on an individual logical line. This is a + domain-specific setting, overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. _cpp-config: + +Options for the C++ domain +-------------------------- + +.. confval:: cpp_index_common_prefix + + A list of prefixes that will be ignored when sorting C++ objects in the + global index. For example ``['awesome_lib::']``. + + .. versionadded:: 1.5 + +.. confval:: cpp_id_attributes + + A list of strings that the parser additionally should accept as attributes. + This can for example be used when attributes have been ``#define`` d for + portability. + + .. versionadded:: 1.5 + +.. confval:: cpp_paren_attributes + + A list of strings that the parser additionally should accept as attributes + with one argument. That is, if ``my_align_as`` is in the list, then + ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have + balanced braces (``()``, ``[]``, and ``{}``). This can for example be used + when attributes have been ``#define`` d for portability. + + .. versionadded:: 1.5 + +.. confval:: cpp_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter will be displayed on an individual logical line. This is a + domain-specific setting, overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +Options for the Python domain +----------------------------- + +.. confval:: python_display_short_literal_types + + This value controls how :py:data:`~typing.Literal` types are displayed. + The setting is a boolean, default ``False``. + + Examples + ~~~~~~~~ + + The examples below use the following :rst:dir:`py:function` directive: + + .. code:: reStructuredText + + .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None + + When ``False``, :py:data:`~typing.Literal` types display as per standard + Python syntax, i.e.: + + .. code:: python + + serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None + + When ``True``, :py:data:`~typing.Literal` types display with a short, + :PEP:`604`-inspired syntax, i.e.: + + .. code:: python + + serve_food(item: "egg" | "spam" | "lobster thermidor") -> None + + .. versionadded:: 6.2 + +.. 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 + +.. confval:: python_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, + each argument or type parameter will be displayed on an individual logical line. + This is a domain-specific setting, + overriding :confval:`maximum_signature_line_length`. + + For the Python domain, the signature length depends on whether + the type parameters or the list of arguments are being formatted. + For the former, the signature length ignores the length of the arguments list; + for the latter, the signature length ignores the length of + the type parameters list. + + For instance, with `python_maximum_signature_line_length = 20`, + only the list of type parameters will be wrapped + while the arguments list will be rendered on a single line + + .. code:: rst + + .. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U) + + .. versionadded:: 7.1 + +Options for the Javascript domain +--------------------------------- + +.. confval:: javascript_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter will be displayed on an individual logical line. This is a + domain-specific setting, overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +Example of configuration file +----------------------------- + +.. literalinclude:: /_static/conf.py.txt + :language: python diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst new file mode 100644 index 0000000..1498ae9 --- /dev/null +++ b/doc/usage/extensions/autodoc.rst @@ -0,0 +1,853 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings +================================================================== + +.. module:: sphinx.ext.autodoc + :synopsis: Include documentation from docstrings. + +.. index:: pair: automatic; documentation + single: docstring + +This extension can import the modules you are documenting, and pull in +documentation from docstrings in a semi-automatic way. + +.. note:: + + For Sphinx (actually, the Python interpreter that executes Sphinx) to find + your module, it must be importable. That means that the module or the + package must be in one of the directories on :data:`sys.path` -- adapt your + :data:`sys.path` in the configuration file accordingly. + +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + +For this to work, the docstrings must of course be written in correct +reStructuredText. You can then use all of the usual Sphinx markup in the +docstrings, and it will end up correctly in the documentation. Together with +hand-written documentation, this technique eases the pain of having to maintain +two locations for documentation, while at the same time avoiding +auto-generated-looking pure API documentation. + +If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, +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://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + + +Directives +---------- + +:mod:`autodoc` provides several directives that are versions of the usual +:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they +import the corresponding module and extract the docstring of the given objects, +inserting them into the page source under a suitable :rst:dir:`py:module`, +:rst:dir:`py:class` etc. directive. + +.. note:: + + Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`, + :rst:dir:`autoclass` will also do so. Likewise, :rst:dir:`automethod` will + respect the current :rst:dir:`py:class`. + + +.. rst:directive:: automodule + autoclass + autoexception + + Document a module, class or exception. All three directives will by default + only insert the docstring of the object itself:: + + .. autoclass:: Noodle + + will produce source like this:: + + .. class:: Noodle + + Noodle's docstring. + + The "auto" directives can also contain content of their own, it will be + inserted into the resulting non-auto directive source after the docstring + (but before any automatic member documentation). + + Therefore, you can also mix automatic and non-automatic member documentation, + like so:: + + .. autoclass:: Noodle + :members: eat, slurp + + .. method:: boil(time=10) + + Boil the noodle *time* minutes. + + .. 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. + + For example:: + + .. automodule:: noodle + :members: + + will document all module members (recursively), and :: + + .. autoclass:: Noodle + :members: + + will document all class member methods and properties. + + By default, autodoc will not generate document for the members that are + private, not having docstrings, inherited from super class, or special + members. + + 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`. + + .. tip:: + + You can use a negated form, :samp:`'no-{flag}'`, as an option of + autodoc directive, to disable it temporarily. For example:: + + .. automodule:: foo + :no-undoc-members: + + .. tip:: + + You can use autodoc directive options to temporarily override or + extend default options which takes list as an input. For example:: + + .. autoclass:: Noodle + :members: eat + :private-members: +_spicy, _garlickly + + .. versionchanged:: 3.5 + The default options can be overridden or extended temporarily. + + * autodoc considers a member private if its docstring contains + ``:meta private:`` in its :ref:`info-field-lists`. + For example: + + .. code-block:: python + + def my_function(my_arg, my_other_arg): + """blah blah blah + + :meta private: + """ + + .. versionadded:: 3.0 + + * autodoc considers a member public if its docstring contains + ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with + an underscore. + For example: + + .. code-block:: python + + def _my_function(my_arg, my_other_arg): + """blah blah blah + + :meta public: + """ + + .. versionadded:: 3.1 + + * autodoc considers a variable member does not have any default value if its + docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. + Example: + + .. code-block:: python + + var1 = None #: :meta hide-value: + + .. versionadded:: 3.5 + + * 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``:: + + .. autoclass:: Noodle + :members: + :inherited-members: + + This can be combined with ``undoc-members`` to document *all* available + members of the class or module. + + It can take an ancestor class not to document inherited members from it. + By default, members of ``object`` class are not documented. To show them + all, give ``None`` to the option. + + For example; If your class ``Foo`` is derived from ``list`` class and + you don't want to document ``list.__len__()``, you should specify a + option ``:inherited-members: list`` to avoid special members of list + class. + + Another example; If your class Foo has ``__str__`` special method and + autodoc directive has both ``inherited-members`` and ``special-members``, + ``__str__`` will be documented as in the past, but other special method + that are not implemented in your class ``Foo``. + + Since v5.0, it can take a comma separated list of ancestor classes. It + allows to suppress inherited members of several classes on the module at + once by specifying the option to :rst:dir:`automodule` directive. + + Note: this will lead to markup errors if the inherited members come from a + module whose docstrings are not reST formatted. + + .. versionadded:: 0.3 + + .. versionchanged:: 3.0 + + It takes an ancestor class name as an argument. + + .. versionchanged:: 5.0 + + It takes a comma separated list of ancestor class names. + + * It's possible to override the signature for explicitly documented callable + objects (functions, methods, classes) with the regular syntax that will + override the signature gained from introspection:: + + .. autoclass:: Noodle(type) + + .. automethod:: eat(persona) + + This is useful if the signature from the method is hidden by a decorator. + + .. versionadded:: 0.4 + + * The :rst:dir:`automodule`, :rst:dir:`autoclass` and + :rst:dir:`autoexception` directives also support a flag option called + ``show-inheritance``. When given, a list of base classes will be inserted + just below the class signature (when used with :rst:dir:`automodule`, this + will be inserted for every class that is documented in the module). + + .. versionadded:: 0.4 + + * All autodoc directives support the ``no-index`` flag option that has the + same effect as for standard :rst:dir:`py:function` etc. directives: no + index entries are generated for the documented object (and all + autodocumented members). + + .. versionadded:: 0.4 + + * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and + ``deprecated`` options that the standard :rst:dir:`py:module` directive + supports. + + .. versionadded:: 0.5 + + * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` + option that can be used to override the global value of + :confval:`autodoc_member_order` for one directive. + + .. versionadded:: 0.6 + + * The directives supporting member documentation also have a + ``exclude-members`` option that can be used to exclude single member names + from documentation, if all members are to be documented. + + .. versionadded:: 0.6 + + * In an :rst:dir:`automodule` directive with the ``members`` option set, only + module members whose ``__module__`` attribute is equal to the module name + as given to ``automodule`` will be documented. This is to prevent + documentation of imported classes or functions. Set the + ``imported-members`` option if you want to prevent this behavior and + document all available members. Note that attributes from imported modules + will not be documented, because attribute documentation is discovered by + parsing the source file of the current module. + + .. versionadded:: 1.2 + + * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent + import errors to halt the building process when some external dependencies + are not importable at build time. + + .. versionadded:: 1.3 + + * As a hint to autodoc extension, you can put a ``::`` separator in between + module name and object name to let autodoc know the correct module name if + it is ambiguous. :: + + .. autoclass:: module.name::Noodle + + * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that + can be used to override the global value of :confval:`autoclass_content`. + + .. versionadded:: 4.1 + +.. rst:directive:: autofunction + autodecorator + autodata + automethod + autoattribute + autoproperty + + These work exactly like :rst:dir:`autoclass` etc., + but do not offer the options used for automatic member documentation. + + :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation`` + option. The option controls how the value of variable is shown. If specified + without arguments, only the name of the variable will be printed, and its value + is not shown:: + + .. autodata:: CD_DRIVE + :annotation: + + If the option specified with arguments, it is printed after the name as a value + of the variable:: + + .. autodata:: CD_DRIVE + :annotation: = your CD device name + + By default, without ``annotation`` option, Sphinx tries to obtain the value of + the variable and print it after the name. + + The ``no-value`` option can be used instead of a blank ``annotation`` to show the + type hint but not the value:: + + .. autodata:: CD_DRIVE + :no-value: + + If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no + effect. + + For module data members and class attributes, documentation can either be put + into a comment with special formatting (using a ``#:`` to start the comment + instead of just ``#``), or in a docstring *after* the definition. Comments + need to be either on a line of their own *before* the definition, or + immediately after the assignment *on the same line*. The latter form is + restricted to one line only. + + This means that in the following class definition, all attributes can be + autodocumented:: + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for class attribute Foo.bar. + #: It can have multiple lines. + bar = 1 + + flox = 1.5 #: Doc comment for Foo.flox. One line only. + + baz = 2 + """Docstring for class attribute Foo.baz.""" + + def __init__(self): + #: Doc comment for instance attribute qux. + self.qux = 3 + + self.spam = 4 + """Docstring for instance attribute spam.""" + + .. versionchanged:: 0.6 + :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract + docstrings. + .. versionchanged:: 1.1 + Comment docs are now allowed on the same line after an assignment. + .. versionchanged:: 1.2 + :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation`` + option. + .. versionchanged:: 2.0 + :rst:dir:`autodecorator` added. + .. versionchanged:: 2.1 + :rst:dir:`autoproperty` added. + .. versionchanged:: 3.4 + :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` + option. + + .. note:: + + If you document decorated functions or methods, keep in mind that autodoc + retrieves its docstrings by importing the module and inspecting the + ``__doc__`` attribute of the given function or method. That means that if + a decorator replaces the decorated function with another, it must copy the + original ``__doc__`` to the new function. + + +Configuration +------------- + +There are also config values that you can set: + +.. confval:: autoclass_content + + This value selects what content will be inserted into the main body of an + :rst:dir:`autoclass` directive. The possible values are: + + ``"class"`` + Only the class' docstring is inserted. This is the default. You can + still document ``__init__`` as a separate method using + :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`. + ``"both"`` + Both the class' and the ``__init__`` method's docstring are concatenated + and inserted. + ``"init"`` + Only the ``__init__`` method's docstring is inserted. + + .. versionadded:: 0.3 + + If the class has no ``__init__`` method or if the ``__init__`` method's + docstring is empty, but the class has a ``__new__`` method's docstring, + it is used instead. + + .. versionadded:: 1.4 + +.. confval:: autodoc_class_signature + + This value selects how the signature will be displayed for the class defined + by :rst:dir:`autoclass` directive. The possible values are: + + ``"mixed"`` + Display the signature with the class name. + ``"separated"`` + Display the signature as a method. + + The default is ``"mixed"``. + + .. versionadded:: 4.1 + +.. confval:: autodoc_member_order + + This value selects if automatically documented members are sorted + alphabetical (value ``'alphabetical'``), by member type (value + ``'groupwise'``) or by source order (value ``'bysource'``). The default is + alphabetical. + + Note that for source order, the module must be a Python module with the + source code available. + + .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support for ``'bysource'``. + +.. confval:: autodoc_default_flags + + This value is a list of autodoc directive flags that should be automatically + applied to all autodoc directives. The supported flags are ``'members'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` + and ``'exclude-members'``. + + .. versionadded:: 1.0 + + .. deprecated:: 1.8 + + Integrated into :confval:`autodoc_default_options`. + +.. confval:: autodoc_default_options + + The default options for autodoc directives. They are applied to all autodoc + directives automatically. It must be a dictionary which maps option names + to the values. For example:: + + autodoc_default_options = { + 'members': 'var1, var2', + 'member-order': 'bysource', + 'special-members': '__init__', + 'undoc-members': True, + 'exclude-members': '__weakref__' + } + + Setting ``None`` or ``True`` to the value is equivalent to giving only the + option name to the directives. + + The supported options are ``'members'``, ``'member-order'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``, + ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and + ``'no-value'``. + + .. versionadded:: 1.8 + + .. versionchanged:: 2.0 + Accepts ``True`` as a value. + + .. versionchanged:: 2.1 + Added ``'imported-members'``. + + .. versionchanged:: 4.1 + Added ``'class-doc-from'``. + + .. versionchanged:: 4.5 + Added ``'no-value'``. + +.. confval:: autodoc_docstring_signature + + Functions imported from C modules cannot be introspected, and therefore the + signature for such functions cannot be automatically determined. However, it + is an often-used convention to put the signature into the first line of the + function's docstring. + + If this boolean value is set to ``True`` (which is the default), autodoc will + look at the first line of the docstring for functions and methods, and if it + looks like a signature, use the line as the signature and remove it from the + docstring content. + + 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 + some external dependencies are not met at build time and break the building + process. You may only specify the root package of the dependencies + themselves and omit the sub-modules: + + .. code-block:: python + + autodoc_mock_imports = ["django"] + + Will mock all imports under the ``django`` package. + + .. versionadded:: 1.3 + + .. versionchanged:: 1.6 + This config value only requires to declare the top-level modules that + should be mocked. + +.. confval:: autodoc_typehints + + This value controls how to represent typehints. The setting takes the + following values: + + * ``'signature'`` -- Show typehints in the signature (default) + * ``'description'`` -- Show typehints as content of the function or method + The typehints of overloaded functions or methods will still be represented + in the signature. + * ``'none'`` -- Do not show typehints + * ``'both'`` -- Show typehints in the signature and as content of + the function or method + + Overloaded functions or methods will not have typehints included in the + description because it is impossible to accurately represent all possible + overloads as a list of parameters. + + .. versionadded:: 2.1 + .. versionadded:: 3.0 + + New option ``'description'`` is added. + + .. versionadded:: 4.1 + + New option ``'both'`` 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. + + With ``"documented_params"``, parameter types will only be annotated if the + parameter is documented in the docstring. The return type is always + annotated (except if it is ``None``). + + .. versionadded:: 4.0 + + .. versionadded:: 5.0 + + New option ``'documented_params'`` is added. + +.. confval:: autodoc_type_aliases + + A dictionary for users defined `type aliases`__ that maps a type name to the + full-qualified object name. It is used to keep type aliases not evaluated in + the document. Defaults to empty (``{}``). + + The type aliases are only available if your program enables :pep:`Postponed + Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import + annotations``. + + For example, there is code using a type alias:: + + from __future__ import annotations + + AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + def f() -> AliasType: + ... + + If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up + from this code as following:: + + .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + ... + + If you set ``autodoc_type_aliases`` as + ``{'AliasType': 'your.module.AliasType'}``, it generates the following document + internally:: + + .. py:function:: f() -> your.module.AliasType: + + ... + + .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases + .. versionadded:: 3.3 + +.. confval:: autodoc_typehints_format + + This value controls the format of typehints. The setting takes the + following values: + + * ``'fully-qualified'`` -- Show the module name and its name of typehints + * ``'short'`` -- Suppress the leading module names of the typehints + (ex. ``io.StringIO`` -> ``StringIO``) (default) + + .. versionadded:: 4.4 + + .. versionchanged:: 5.0 + + The default setting was changed to ``'short'`` + +.. 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 + importing modules. + If ``False`` is given, autodoc forcedly suppresses the error if the imported + module emits warnings. By default, ``True``. + +.. confval:: autodoc_inherit_docstrings + + This value controls the docstrings inheritance. + If set to True the docstring for classes or methods, if not explicitly set, + is inherited from parents. + + The default is ``True``. + + .. versionadded:: 1.7 + +.. confval:: suppress_warnings + :no-index: + + :mod:`autodoc` supports to suppress warning messages via + :confval:`suppress_warnings`. It allows following warnings types in + addition: + + * autodoc + * autodoc.import_object + + +Docstring preprocessing +----------------------- + +autodoc provides the following additional events: + +.. event:: autodoc-process-docstring (app, what, name, obj, options, lines) + + .. versionadded:: 0.4 + + Emitted when autodoc has read and processed a docstring. *lines* is a list + of strings -- the lines of the processed docstring -- that the event handler + can modify **in place** to change what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param lines: the lines of the docstring, see above + +.. event:: autodoc-before-process-signature (app, obj, bound_method) + + .. versionadded:: 2.4 + + Emitted before autodoc formats a signature for an object. The event handler + can modify an object to change its signature. + + :param app: the Sphinx application object + :param obj: the object itself + :param bound_method: a boolean indicates an object is bound method or not + +.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation) + + .. versionadded:: 0.5 + + Emitted when autodoc has formatted a signature for an object. The event + handler can return a new tuple ``(signature, return_annotation)`` to change + what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param signature: function signature, as a string of the form + ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't + succeed and signature wasn't specified in the directive. + :param return_annotation: function return annotation as a string of the form + ``" -> annotation"``, or ``None`` if there is no return annotation + +The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly +needed docstring processing in event :event:`autodoc-process-docstring`: + +.. autofunction:: cut_lines +.. autofunction:: between + +.. event:: autodoc-process-bases (app, name, obj, options, bases) + + Emitted when autodoc has read and processed a class to determine the + base-classes. *bases* is a list of classes that the event handler can + modify **in place** to change what Sphinx puts into the output. It's + emitted only if ``show-inheritance`` option given. + + :param app: the Sphinx application object + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the class directive + :param bases: the list of base classes signature. see above. + + .. versionadded:: 4.1 + .. versionchanged:: 4.3 + + ``bases`` can contain a string as a base class name. It will be processed + as reST mark-up'ed text. + + +Skipping members +---------------- + +autodoc allows the user to define a custom method for determining whether a +member should be included in the documentation by using the following event: + +.. event:: autodoc-skip-member (app, what, name, obj, skip, options) + + .. versionadded:: 0.5 + + Emitted when autodoc has to decide whether a member should be included in the + documentation. The member is excluded if a handler returns ``True``. It is + included if the handler returns ``False``. + + If more than one enabled extension handles the ``autodoc-skip-member`` + event, autodoc will use the first non-``None`` value returned by a handler. + Handlers should return ``None`` to fall back to the skipping behavior of + autodoc and other enabled extensions. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param skip: a boolean indicating if autodoc will skip this member if the + user handler does not override the decision + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst new file mode 100644 index 0000000..b5b9b51 --- /dev/null +++ b/doc/usage/extensions/autosectionlabel.rst @@ -0,0 +1,56 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title +============================================================================== + +.. module:: sphinx.ext.autosectionlabel + :synopsis: Allow reference section its title. + +.. versionadded:: 1.4 + +This extension allows you to refer sections its title. This affects to the +reference role (:rst:role:`ref`). + +For example:: + + A Plain Title + ------------- + + This is the text of the section. + + It refers to the section title, see :ref:`A Plain Title`. + + +Internally, this extension generates the labels for each section. If same +section names are used in whole of document, any one is used for a target by +default. The ``autosectionlabel_prefix_document`` configuration variable can be +used to make headings which appear multiple times but in different documents +unique. + + +Configuration +------------- + +.. confval:: autosectionlabel_prefix_document + + True to prefix each section label with the name of the document it is in, + followed by a colon. For example, ``index:Introduction`` for a section + called ``Introduction`` that appears in document ``index.rst``. Useful for + avoiding ambiguity when the same section heading appears in different + documents. + +.. confval:: autosectionlabel_maxdepth + + If set, autosectionlabel chooses the sections for labeling by its depth. For + example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated + only for top level sections, and deeper sections are not labeled. It + defaults to ``None`` (disabled). + + +Debugging +--------- + +The ``WARNING: undefined label`` indicates that your reference in +:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv`` +(see :option:`-v`) will print all section names and the labels that have been +generated for them. This output can help finding the right reference label. diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst new file mode 100644 index 0000000..a18460b --- /dev/null +++ b/doc/usage/extensions/autosummary.rst @@ -0,0 +1,364 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries +=========================================================== + +.. module:: sphinx.ext.autosummary + :synopsis: Generate autodoc summaries + +.. versionadded:: 0.6 + +This extension generates function/method/attribute summary lists, similar to +those output e.g. by Epydoc and other API doc generation tools. This is +especially useful when your docstrings are long and detailed, and putting each +one of them on a separate page makes them easier to read. + +The :mod:`sphinx.ext.autosummary` extension does this in two parts: + +1. There is an :rst:dir:`autosummary` directive for generating summary listings + that contain links to the documented items, and short summary blurbs + extracted from their docstrings. + +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 + + Insert a table that contains links to documented items, and a short summary + blurb (the first sentence of the docstring) for each of them. + + The :rst:dir:`autosummary` directive can also optionally serve as a + :rst:dir:`toctree` entry for the included items. Optionally, stub + ``.rst`` files for these items can also be automatically generated + when :confval:`autosummary_generate` is `True`. + + For example, :: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + produces a table like this: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + .. currentmodule:: sphinx.ext.autosummary + + Autosummary preprocesses the docstrings and signatures with the same + :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` + hooks as :mod:`~sphinx.ext.autodoc`. + + **Options** + + * If you want the :rst:dir:`autosummary` table to also serve as a + :rst:dir:`toctree` entry, use the ``toctree`` option, for example:: + + .. autosummary:: + :toctree: DIRNAME + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + The ``toctree`` option also signals to the :program:`sphinx-autogen` script + that stub pages should be generated for the entries listed in this + directive. The option accepts a directory name as an argument; + :program:`sphinx-autogen` will by default place its output in this + directory. If no argument is given, output is placed in the same directory + as the file that contains the directive. + + You can also use ``caption`` option to give a caption to the toctree. + + .. versionadded:: 3.1 + + caption option added. + + * If you don't want the :rst:dir:`autosummary` to show function signatures in + the listing, include the ``nosignatures`` option:: + + .. autosummary:: + :nosignatures: + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + * You can specify a custom template with the ``template`` option. + For example, :: + + .. autosummary:: + :template: mytemplate.rst + + sphinx.environment.BuildEnvironment + + would use the template :file:`mytemplate.rst` in your + :confval:`templates_path` to generate the pages for all entries + listed. See `Customizing templates`_ below. + + .. versionadded:: 1.0 + + * You can specify the ``recursive`` option to generate documents for + modules and sub-packages recursively. It defaults to disabled. + For example, :: + + .. autosummary:: + :recursive: + + sphinx.environment.BuildEnvironment + + .. versionadded:: 3.1 + + +:program:`sphinx-autogen` -- generate autodoc stub pages +-------------------------------------------------------- + +The :program:`sphinx-autogen` script can be used to conveniently generate stub +documentation pages for items included in :rst:dir:`autosummary` listings. + +For example, the command :: + + $ sphinx-autogen -o generated *.rst + +will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have +the ``:toctree:`` option set, and output corresponding stub pages in directory +``generated`` for all documented items. The generated pages by default contain +text of the form:: + + sphinx.util.relative_uri + ======================== + + .. autofunction:: sphinx.util.relative_uri + +If the ``-o`` option is not given, the script will place the output files in the +directories specified in the ``:toctree:`` options. + +For more information, refer to the :doc:`sphinx-autogen documentation +</man/sphinx-autogen>` + + +Generating stub pages automatically +----------------------------------- + +If you do not want to create stub pages with :program:`sphinx-autogen`, you can +also use these config values: + +.. confval:: autosummary_context + + A dictionary of values to pass into the template engine's context for + autosummary stubs files. + + .. versionadded:: 3.1 + +.. confval:: autosummary_generate + + Boolean indicating whether to scan all found documents for autosummary + 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. + + The new files will be placed in the directories specified in the + ``:toctree:`` options of the directives. + + .. versionchanged:: 2.3 + + 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. + Defaults to true (enabled). + + .. versionadded:: 3.0 + +.. confval:: autosummary_mock_imports + + This value contains a list of modules to be mocked up. See + :confval:`autodoc_mock_imports` for more details. It defaults to + :confval:`autodoc_mock_imports`. + + .. versionadded:: 2.0 + +.. confval:: autosummary_imported_members + + A boolean flag indicating whether to document classes and functions imported + in modules. Default is ``False`` + + .. versionadded:: 2.1 + + .. versionchanged:: 4.4 + + If ``autosummary_ignore_module_all`` is ``False``, this configuration + value is ignored for members listed in ``__all__``. + +.. confval:: autosummary_ignore_module_all + + If ``False`` and a module has the ``__all__`` attribute set, autosummary + documents every member listed in ``__all__`` and no others. Default is + ``True`` + + Note that if an imported member is listed in ``__all__``, it will be + documented regardless of the value of ``autosummary_imported_members``. To + match the behaviour of ``from module import *``, set + ``autosummary_ignore_module_all`` to False and + ``autosummary_imported_members`` to True. + + .. versionadded:: 4.4 + +.. confval:: autosummary_filename_map + + A dict mapping object names to filenames. This is necessary to avoid + filename conflicts where multiple objects have names that are + indistinguishable when case is ignored, on file systems where filenames + are case-insensitive. + + .. versionadded:: 3.2 + +.. _autosummary-customizing-templates: + +Customizing templates +--------------------- + +.. versionadded:: 1.0 + +You can customize the stub page templates, in a similar way as the HTML Jinja +templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge` +is not supported.) + +.. note:: + + If you find yourself spending much time tailoring the stub templates, this + may indicate that it's a better idea to write custom narrative documentation + instead. + +Autosummary uses the following Jinja template files: + +- :file:`autosummary/base.rst` -- fallback template +- :file:`autosummary/module.rst` -- template for modules +- :file:`autosummary/class.rst` -- template for classes +- :file:`autosummary/function.rst` -- template for functions +- :file:`autosummary/attribute.rst` -- template for class attributes +- :file:`autosummary/method.rst` -- template for class methods + +The following variables are available in the templates: + +.. currentmodule:: None + +.. data:: name + + Name of the documented object, excluding the module and class parts. + +.. data:: objname + + Name of the documented object, excluding the module parts. + +.. data:: fullname + + Full name of the documented object, including module and class parts. + +.. data:: objtype + + Type of the documented object, one of ``"module"``, ``"function"``, + ``"class"``, ``"method"``, ``"attribute"``, ``"data"``, ``"object"``, + ``"exception"``, ``"newvarattribute"``, ``"newtypedata"``, ``"property"``. + +.. data:: module + + Name of the module the documented object belongs to. + +.. data:: class + + Name of the class the documented object belongs to. Only available for + methods and attributes. + +.. data:: underline + + A string containing ``len(full_name) * '='``. Use the ``underline`` filter + instead. + +.. data:: members + + List containing names of all members of the module or class. Only available + for modules and classes. + +.. data:: inherited_members + + List containing names of all inherited members of class. Only available for + classes. + + .. versionadded:: 1.8.0 + +.. data:: functions + + List containing names of "public" functions in the module. Here, "public" + means that the name does not start with an underscore. Only available + for modules. + +.. data:: classes + + List containing names of "public" classes in the module. Only available for + modules. + +.. data:: exceptions + + List containing names of "public" exceptions in the module. Only available + for modules. + +.. data:: methods + + List containing names of "public" methods in the class. Only available for + classes. + +.. data:: attributes + + List containing names of "public" attributes in the class/module. Only + available for classes and modules. + + .. versionchanged:: 3.1 + + Attributes of modules are supported. + +.. data:: modules + + List containing names of "public" modules in the package. Only available for + modules that are packages and the ``recursive`` option is on. + + .. versionadded:: 3.1 + +Additionally, the following filters are available + +.. function:: escape(s) + + Escape any special characters in the text to be used in formatting RST + contexts. For instance, this prevents asterisks making things bold. This + replaces the builtin Jinja `escape filter`_ that does html-escaping. + +.. function:: underline(s, line='=') + :no-index: + + Add a title underline to a piece of text. + +For instance, ``{{ fullname | escape | underline }}`` should be used to produce +the title of a page. + +.. note:: + + You can use the :rst:dir:`autosummary` directive in the stub pages. + Stub pages are generated also based on these directives. + +.. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst new file mode 100644 index 0000000..1390ebf --- /dev/null +++ b/doc/usage/extensions/coverage.rst @@ -0,0 +1,99 @@ +:mod:`sphinx.ext.coverage` -- Collect doc coverage stats +======================================================== + +.. module:: sphinx.ext.coverage + :synopsis: Check Python modules and C API for coverage in the documentation. + +This extension features one additional builder, the :class:`CoverageBuilder`. + +.. class:: CoverageBuilder + + To use this builder, activate the coverage extension in your configuration + file and give ``-b coverage`` on the command line. + +.. todo:: Write this section. + +Several configuration values can be used to specify what the builder +should check: + +.. confval:: coverage_ignore_modules + +.. confval:: coverage_ignore_functions + +.. 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. + + .. _Python regular expressions: https://docs.python.org/library/re + + .. versionadded:: 2.1 + +.. confval:: coverage_c_path + +.. confval:: coverage_c_regexes + +.. confval:: coverage_ignore_c_items + +.. confval:: coverage_write_headline + + Set to ``False`` to not write headlines. + + .. versionadded:: 1.1 + +.. confval:: coverage_skip_undoc_in_source + + Skip objects that are not documented in the source with a docstring. + ``False`` by default. + + .. versionadded:: 1.1 + +.. confval:: coverage_show_missing_items + + Print objects that are missing to standard output also. + ``False`` by default. + + .. versionadded:: 3.1 + +.. confval:: coverage_statistics_to_report + + Print a tabluar report of the coverage statistics to the coverage report. + ``True`` by default. + + Example output: + + .. code-block:: text + + +-----------------------+----------+--------------+ + | Module | Coverage | Undocumented | + +=======================+==========+==============+ + | package.foo_module | 100.00% | 0 | + +-----------------------+----------+--------------+ + | package.bar_module | 83.33% | 1 | + +-----------------------+----------+--------------+ + + .. versionadded:: 7.2 + +.. confval:: coverage_statistics_to_stdout + + Print a tabluar report of the coverage statistics to standard output. + ``False`` by default. + + Example output: + + .. code-block:: text + + +-----------------------+----------+--------------+ + | Module | Coverage | Undocumented | + +=======================+==========+==============+ + | package.foo_module | 100.00% | 0 | + +-----------------------+----------+--------------+ + | package.bar_module | 83.33% | 1 | + +-----------------------+----------+--------------+ + + .. versionadded:: 7.2 diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst new file mode 100644 index 0000000..1848e1f --- /dev/null +++ b/doc/usage/extensions/doctest.rst @@ -0,0 +1,385 @@ +.. highlight:: rest + +:mod:`sphinx.ext.doctest` -- Test snippets in the documentation +=============================================================== + +.. module:: sphinx.ext.doctest + :synopsis: Test snippets in the documentation. + +.. index:: pair: automatic; testing + single: doctest + pair: testing; snippets + + +It is often helpful to include snippets of code in your documentation and +demonstrate the results of executing them. But it is important to ensure that +the documentation stays up-to-date with the code. + +This extension allows you to test such code snippets in the documentation in +a natural way. If you mark the code blocks as shown here, the ``doctest`` +builder will collect them and run them as doctest tests. + +Within each document, you can assign each snippet to a *group*. Each group +consists of: + +* zero or more *setup code* blocks (e.g. importing the module to test) +* one or more *test* blocks + +When building the docs with the ``doctest`` builder, groups are collected for +each document and run one after the other, first executing setup code blocks, +then the test blocks in the order they appear in the file. + +There are two kinds of test blocks: + +* *doctest-style* blocks mimic interactive sessions by interleaving Python code + (including the interpreter prompt) and output. + +* *code-output-style* blocks consist of an ordinary piece of Python code, and + optionally, a piece of output for that code. + + +Directives +---------- + +The *group* argument below is interpreted as follows: if it is empty, the block +is assigned to the group named ``default``. If it is ``*``, the block is +assigned to all groups (including the ``default`` group). Otherwise, it must be +a comma-separated list of group names. + +.. rst:directive:: .. testsetup:: [group] + + A setup code block. This code is not shown in the output for other builders, + but executed before the doctests of the group(s) it belongs to. + + +.. rst:directive:: .. testcleanup:: [group] + + A cleanup code block. This code is not shown in the output for other + builders, but executed after the doctests of the group(s) it belongs to. + + .. versionadded:: 1.1 + + +.. rst:directive:: .. doctest:: [group] + + A doctest-style code block. You can use standard :mod:`doctest` flags for + controlling how actual output is compared with what you give as output. The + default set of flags is specified by the :confval:`doctest_default_flags` + configuration variable. + + This directive supports five options: + + * ``hide``, a flag option, hides the doctest block in other builders. By + default it is shown as a highlighted doctest block. + + * ``options``, a string option, can be used to give a comma-separated list of + doctest flags that apply to each example in the tests. (You still can give + explicit flags per example, with doctest comments, but they will show up in + other builders too.) + + * ``pyversion``, a string option, can be used to specify the required Python + version for the example to be tested. For instance, in the following case + the example will be tested only for Python versions greater than 3.10:: + + .. doctest:: + :pyversion: > 3.10 + + The following operands are supported: + + * ``~=``: Compatible release clause + * ``==``: Version matching clause + * ``!=``: Version exclusion clause + * ``<=``, ``>=``: Inclusive ordered comparison clause + * ``<``, ``>``: Exclusive ordered comparison clause + * ``===``: Arbitrary equality clause. + + ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers + <440#version-specifiers>`. + + .. versionadded:: 1.6 + + .. versionchanged:: 1.7 + + Supported PEP-440 operands and notations + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + Note that like with standard doctests, you have to use ``<BLANKLINE>`` to + signal a blank line in the expected output. The ``<BLANKLINE>`` is removed + when building presentation output (HTML, LaTeX etc.). + + Also, you can give inline doctest options, like in doctest:: + + >>> datetime.date.now() # doctest: +SKIP + datetime.date(2008, 1, 1) + + They will be respected when the test is run, but stripped from presentation + output. + + +.. rst:directive:: .. testcode:: [group] + + A code block for a code-output-style test. + + This directive supports three options: + + * ``hide``, a flag option, hides the code block in other builders. By + default it is shown as a highlighted code block. + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + .. note:: + + Code in a ``testcode`` block is always executed all at once, no matter how + many statements it contains. Therefore, output will *not* be generated + for bare expressions -- use ``print``. Example:: + + .. testcode:: + + 1+1 # this will give no output! + print(2+2) # this will give output + + .. testoutput:: + + 4 + + Also, please be aware that since the doctest module does not support + mixing regular output and an exception message in the same snippet, this + applies to testcode/testoutput as well. + + +.. rst:directive:: .. testoutput:: [group] + + The corresponding output, or the exception message, for the last + :rst:dir:`testcode` block. + + This directive supports four options: + + * ``hide``, a flag option, hides the output block in other builders. By + default it is shown as a literal block without highlighting. + + * ``options``, a string option, can be used to give doctest flags + (comma-separated) just like in normal doctest blocks. + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + Example:: + + .. testcode:: + + print('Output text.') + + .. testoutput:: + :hide: + :options: -ELLIPSIS, +NORMALIZE_WHITESPACE + + Output text. + +The following is an example for the usage of the directives. The test via +:rst:dir:`doctest` and the test via :rst:dir:`testcode` and +:rst:dir:`testoutput` are equivalent. :: + + The parrot module + ================= + + .. testsetup:: * + + import parrot + + The parrot module is a module about parrots. + + Doctest example: + + .. doctest:: + + >>> parrot.voom(3000) + This parrot wouldn't voom if you put 3000 volts through it! + + Test-Output example: + + .. testcode:: + + parrot.voom(3000) + + This would output: + + .. testoutput:: + + This parrot wouldn't voom if you put 3000 volts through it! + + +Skipping tests conditionally +---------------------------- + +``skipif``, a string option, can be used to skip directives conditionally. This +may be useful e.g. when a different set of tests should be run depending on the +environment (hardware, network/VPN, optional dependencies or different versions +of dependencies). The ``skipif`` option is supported by all of the doctest +directives. Below are typical use cases for ``skipif`` when used for different +directives: + +- :rst:dir:`testsetup` and :rst:dir:`testcleanup` + + - conditionally skip test setup and/or cleanup + - customize setup/cleanup code per environment + +- :rst:dir:`doctest` + + - conditionally skip both a test and its output verification + +- :rst:dir:`testcode` + + - conditionally skip a test + - customize test code per environment + +- :rst:dir:`testoutput` + + - conditionally skip output assertion for a skipped test + - expect different output depending on the environment + +The value of the ``skipif`` option is evaluated as a Python expression. If the +result is a true value, the directive is omitted from the test run just as if +it wasn't present in the file at all. + +Instead of repeating an expression, the :confval:`doctest_global_setup` +configuration option can be used to assign it to a variable which can then be +used instead. + +Here's an example which skips some tests if Pandas is not installed: + +.. code-block:: py + :caption: conf.py + + extensions = ['sphinx.ext.doctest'] + doctest_global_setup = ''' + try: + import pandas as pd + except ImportError: + pd = None + ''' + +.. code-block:: rst + :caption: contents.rst + + .. testsetup:: + :skipif: pd is None + + data = pd.Series([42]) + + .. doctest:: + :skipif: pd is None + + >>> data.iloc[0] + 42 + + .. testcode:: + :skipif: pd is None + + print(data.iloc[-1]) + + .. testoutput:: + :skipif: pd is None + + 42 + + +Configuration +------------- + +The doctest extension uses the following configuration values: + +.. confval:: doctest_default_flags + + By default, these options are enabled: + + - ``ELLIPSIS``, allowing you to put ellipses in the expected output that + match anything in the actual output; + - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost + colon and any module information in the exception name to be ignored; + - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is + given -- the default behavior of accepting this substitution is a relic of + pre-Python 2.2 times. + + .. versionadded:: 1.5 + +.. confval:: doctest_show_successes + + Defaults to ``True``. + Controls whether successes are reported. + + For a project with many doctests, + it may be useful to set this to ``False`` to only highlight failures. + + .. versionadded:: 7.2 + +.. confval:: doctest_path + + A list of directories that will be added to :data:`sys.path` when the doctest + builder is used. (Make sure it contains absolute paths.) + +.. confval:: doctest_global_setup + + Python code that is treated like it were put in a ``testsetup`` directive for + *every* file that is tested, and for every group. You can use this to + e.g. import modules you will always need in your doctests. + + .. versionadded:: 0.6 + +.. confval:: doctest_global_cleanup + + Python code that is treated like it were put in a ``testcleanup`` directive + for *every* file that is tested, and for every group. You can use this to + e.g. remove any temporary files that the tests leave behind. + + .. versionadded:: 1.1 + +.. confval:: doctest_test_doctest_blocks + + If this is a nonempty string (the default is ``'default'``), standard reST + doctest blocks will be tested too. They will be assigned to the group name + given. + + reST doctest blocks are simply doctests put into a paragraph of their own, + like so:: + + Some documentation text. + + >>> print(1) + 1 + + Some more documentation text. + + (Note that no special ``::`` is used to introduce a doctest block; docutils + recognizes them from the leading ``>>>``. Also, no additional indentation is + used, though it doesn't hurt.) + + If this value is left at its default value, the above snippet is interpreted + by the doctest builder exactly like the following:: + + Some documentation text. + + .. doctest:: + + >>> print(1) + 1 + + Some more documentation text. + + This feature makes it easy for you to test doctests in docstrings included + with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a + special directive. + + Note though that you can't have blank lines in reST doctest blocks. They + will be interpreted as one block ending and another one starting. Also, + removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in + :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` + to achieve that in all code blocks with Python console content. diff --git a/doc/usage/extensions/duration.rst b/doc/usage/extensions/duration.rst new file mode 100644 index 0000000..1213811 --- /dev/null +++ b/doc/usage/extensions/duration.rst @@ -0,0 +1,11 @@ +:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing +==================================================================== + +.. module:: sphinx.ext.duration + :synopsis: Measure durations of Sphinx processing + +.. versionadded:: 2.4 + +This extension measures durations of Sphinx processing and show its +result at end of the build. It is useful for inspecting what document +is slowly built. diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py new file mode 100644 index 0000000..434fa3b --- /dev/null +++ b/doc/usage/extensions/example_google.py @@ -0,0 +1,309 @@ +"""Example Google style docstrings. + +This module demonstrates documentation as specified by the `Google Python +Style Guide`_. Docstrings may extend over multiple lines. Sections are created +with a section header and a colon followed by a block of indented text. + +Example: + Examples can be given using either the ``Example`` or ``Examples`` + sections. Sections support any reStructuredText formatting, including + literal blocks:: + + $ python example_google.py + +Section breaks are created by resuming unindented text. Section breaks +are also implicitly created anytime a new section starts. + +Attributes: + module_level_variable1 (int): Module level variables may be documented in + either the ``Attributes`` section of the module docstring, or in an + inline docstring immediately following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + +Todo: + * For module TODOs + * You have to also use ``sphinx.ext.todo`` extension + +.. _Google Python Style Guide: + https://google.github.io/styleguide/pyguide.html + +""" + +module_level_variable1 = 12345 + +module_level_variable2 = 98765 +"""int: Module level variable documented inline. + +The docstring may span multiple lines. The type may optionally be specified +on the first line, separated by a colon. +""" + + +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + :pep:`484` type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Args: + param1 (int): The first parameter. + param2 (str): The second parameter. + + Returns: + bool: The return value. True for success, False otherwise. + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + The return value. True for success, False otherwise. + + """ + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Args`` section. The name + of each parameter is required. The type and description of each parameter + is optional, but should be included if not obvious. + + If ``*args`` or ``**kwargs`` are accepted, + they should be listed as ``*args`` and ``**kwargs``. + + The format for a parameter is:: + + name (type): description + The description may span multiple lines. Following + lines should be indented. The "(type)" is optional. + + Multiple paragraphs are supported in parameter + descriptions. + + Args: + param1 (int): The first parameter. + param2 (:obj:`str`, optional): The second parameter. Defaults to None. + Second line of description should be indented. + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Returns: + bool: True if successful, False otherwise. + + The return type is optional and may be specified at the beginning of + the ``Returns`` section followed by a colon. + + The ``Returns`` section may span multiple lines and paragraphs. + Following lines should be indented to match the first line. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises: + AttributeError: The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError: If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Args: + n (int): The upper limit of the range to generate, from 0 to `n` - 1. + + Yields: + int: The next number in the range of 0 to `n` - 1. + + Examples: + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print([i for i in example_generator(4)]) + [0, 1, 2, 3] + + """ + yield from range(n) + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + msg (str): Human readable string describing the exception. + code (:obj:`int`, optional): Error code. + + Attributes: + msg (str): Human readable string describing the exception. + code (int): Exception error code. + + """ + + def __init__(self, msg, code): + self.msg = msg + self.code = code + + +class ExampleClass: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. Alternatively, attributes may be documented + inline with the attribute's declaration (see __init__ method below). + + Properties created with the ``@property`` decorator should be documented + in the property's getter method. + + Attributes: + attr1 (str): Description of `attr1`. + attr2 (:obj:`int`, optional): Description of `attr2`. + + """ + + def __init__(self, param1, param2, param3): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1 (str): Description of `param1`. + param2 (:obj:`int`, optional): Description of `param2`. Multiple + lines are supported. + param3 (list(str)): Description of `param3`. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 #: Doc comment *inline* with attribute + + #: list(str): Doc comment *before* attribute, with type specified + self.attr4 = ['attr4'] + + self.attr5 = None + """str: Docstring *after* attribute, with type specified.""" + + @property + def readonly_property(self): + """str: Properties should be documented in their getter method.""" + return 'readonly_property' + + @property + def readwrite_property(self): + """list(str): Properties with both a getter and setter + should only be documented in their getter method. + + If the setter method contains notable behavior, it should be + mentioned here. + """ + return ['readwrite_property'] + + @readwrite_property.setter + def readwrite_property(self, value): + value + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are not included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output, if + ``napoleon_include_special_with_doc`` is set to True. + + This behavior can be enabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = True + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass + +class ExamplePEP526Class: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. If ``napoleon_attr_annotations`` + is True, types can be specified in the class body using ``PEP 526`` + annotations. + + Attributes: + attr1: Description of `attr1`. + attr2: Description of `attr2`. + + """ + + attr1: str + attr2: int diff --git a/doc/usage/extensions/example_google.rst b/doc/usage/extensions/example_google.rst new file mode 100644 index 0000000..a06f161 --- /dev/null +++ b/doc/usage/extensions/example_google.rst @@ -0,0 +1,17 @@ +:orphan: + +.. _example_google: + +Example Google Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_numpy` + +.. only:: builder_html + + Download: :download:`example_google.py <example_google.py>` + +.. literalinclude:: example_google.py + :language: python diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py new file mode 100644 index 0000000..2346b1e --- /dev/null +++ b/doc/usage/extensions/example_numpy.py @@ -0,0 +1,350 @@ +"""Example NumPy style docstrings. + +This module demonstrates documentation as specified by the `NumPy +Documentation HOWTO`_. Docstrings may extend over multiple lines. Sections +are created with a section header followed by an underline of equal length. + +Example +------- +Examples can be given using either the ``Example`` or ``Examples`` +sections. Sections support any reStructuredText formatting, including +literal blocks:: + + $ python example_numpy.py + + +Section breaks are created with two blank lines. Section breaks are also +implicitly created anytime a new section starts. Section bodies *may* be +indented: + +Notes +----- + This is an example of an indented section. It's like any other section, + but the body is indented to help it stand out from surrounding text. + +If a section is indented, then a section break is created by +resuming unindented text. + +Attributes +---------- +module_level_variable1 : int + Module level variables may be documented in either the ``Attributes`` + section of the module docstring, or in an inline docstring immediately + following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + + +.. _NumPy docstring standard: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + +""" + +module_level_variable1 = 12345 + +module_level_variable2 = 98765 +"""int: Module level variable documented inline. + +The docstring may span multiple lines. The type may optionally be specified +on the first line, separated by a colon. +""" + + +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + :pep:`484` type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Parameters + ---------- + param1 : int + The first parameter. + param2 : str + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + The return type must be duplicated in the docstring to comply + with the NumPy docstring style. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Parameters`` section. + The name of each parameter is required. The type and description of each + parameter is optional, but should be included if not obvious. + + If ``*args`` or ``**kwargs`` are accepted, + they should be listed as ``*args`` and ``**kwargs``. + + The format for a parameter is:: + + name : type + description + + The description may span multiple lines. Following lines + should be indented to match the first line of the description. + The ": type" is optional. + + Multiple paragraphs are supported in parameter + descriptions. + + Parameters + ---------- + param1 : int + The first parameter. + param2 : :obj:`str`, optional + The second parameter. + *args + Variable length argument list. + **kwargs + Arbitrary keyword arguments. + + Returns + ------- + bool + True if successful, False otherwise. + + The return type is not optional. The ``Returns`` section may span + multiple lines and paragraphs. Following lines should be indented to + match the first line of the description. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises + ------ + AttributeError + The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError + If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Parameters + ---------- + n : int + The upper limit of the range to generate, from 0 to `n` - 1. + + Yields + ------ + int + The next number in the range of 0 to `n` - 1. + + Examples + -------- + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print([i for i in example_generator(4)]) + [0, 1, 2, 3] + + """ + yield from range(n) + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + msg : str + Human readable string describing the exception. + code : :obj:`int`, optional + Numeric error code. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + code : int + Numeric error code. + + """ + + def __init__(self, msg, code): + self.msg = msg + self.code = code + + +class ExampleClass: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. Alternatively, attributes may be documented + inline with the attribute's declaration (see __init__ method below). + + Properties created with the ``@property`` decorator should be documented + in the property's getter method. + + Attributes + ---------- + attr1 : str + Description of `attr1`. + attr2 : :obj:`int`, optional + Description of `attr2`. + + """ + + def __init__(self, param1, param2, param3): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 : str + Description of `param1`. + param2 : list(str) + Description of `param2`. Multiple + lines are supported. + param3 : :obj:`int`, optional + Description of `param3`. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 #: Doc comment *inline* with attribute + + #: list(str): Doc comment *before* attribute, with type specified + self.attr4 = ["attr4"] + + self.attr5 = None + """str: Docstring *after* attribute, with type specified.""" + + @property + def readonly_property(self): + """str: Properties should be documented in their getter method.""" + return "readonly_property" + + @property + def readwrite_property(self): + """list(str): Properties with both a getter and setter + should only be documented in their getter method. + + If the setter method contains notable behavior, it should be + mentioned here. + """ + return ["readwrite_property"] + + @readwrite_property.setter + def readwrite_property(self, value): + value + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are not included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output, if + ``napoleon_include_special_with_doc`` is set to True. + + This behavior can be enabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = True + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass diff --git a/doc/usage/extensions/example_numpy.rst b/doc/usage/extensions/example_numpy.rst new file mode 100644 index 0000000..38d3439 --- /dev/null +++ b/doc/usage/extensions/example_numpy.rst @@ -0,0 +1,17 @@ +:orphan: + +.. _example_numpy: + +Example NumPy Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_google` + +.. only:: builder_html + + Download: :download:`example_numpy.py <example_numpy.py>` + +.. literalinclude:: example_numpy.py + :language: python diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst new file mode 100644 index 0000000..97359ab --- /dev/null +++ b/doc/usage/extensions/extlinks.rst @@ -0,0 +1,69 @@ +:mod:`sphinx.ext.extlinks` -- Markup to shorten external links +============================================================== + +.. module:: sphinx.ext.extlinks + :synopsis: Allow inserting external links with common base URLs easily. +.. moduleauthor:: Georg Brandl + +.. versionadded:: 1.0 + +This extension is meant to help with the common pattern of having many external +links that point to URLs on one and the same site, e.g. links to bug trackers, +version control web interfaces, or simply subpages in other websites. It does +so by providing aliases to base URLs, so that you only need to give the subpage +name when creating a link. + +Let's assume that you want to include many links to issues at the Sphinx +tracker, at :samp:`https://github.com/sphinx-doc/sphinx/issues/{num}`. Typing +this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks` +to avoid repeating yourself. + +The extension adds a config value: + +.. confval:: extlinks + + This config value must be a dictionary of external sites, mapping unique + short alias names to a *base URL* and a *caption*. For example, to create an + alias for the above mentioned issues, you would add :: + + extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', + 'issue %s')} + + Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This + then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. + As you can see, the target given in the role is substituted in the *base URL* + in the place of ``%s``. + + The link caption depends on the second item in the tuple, the *caption*: + + - If *caption* is ``None``, the link caption is the full URL. + - If *caption* is a string, then it must contain ``%s`` exactly once. In + this case the link caption is *caption* with the partial URL substituted + for ``%s`` -- in the above example, the link caption would be + ``issue 123``. + + To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``:: + + extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', + '[K&R; page %s]')} + + You can also use the usual "explicit title" syntax supported by other roles + that generate links, i.e. ``:issue:`this issue <123>```. In this case, the + *caption* is not relevant. + + .. versionchanged:: 4.0 + + Support to substitute by '%s' in the caption. + +.. note:: + + Since links are generated from the role in the reading stage, they appear as + ordinary links to e.g. the ``linkcheck`` builder. + +.. confval:: extlinks_detect_hardcoded_links + + If enabled, extlinks emits a warning if a hardcoded link is replaceable + by an extlink, and suggests a replacement via warning. It defaults to + ``False``. + + .. versionadded:: 4.5 diff --git a/doc/usage/extensions/githubpages.rst b/doc/usage/extensions/githubpages.rst new file mode 100644 index 0000000..6d56a30 --- /dev/null +++ b/doc/usage/extensions/githubpages.rst @@ -0,0 +1,16 @@ +:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages +================================================================== + +.. module:: sphinx.ext.githubpages + :synopsis: Publish HTML docs in GitHub Pages + +.. versionadded:: 1.4 + +.. versionchanged:: 2.0 + Support ``CNAME`` file + +This extension creates ``.nojekyll`` file on generated HTML directory to publish +the document on GitHub Pages. + +It also creates a ``CNAME`` file for custom domains when :confval:`html_baseurl` +set. diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst new file mode 100644 index 0000000..c134f6d --- /dev/null +++ b/doc/usage/extensions/graphviz.rst @@ -0,0 +1,239 @@ +.. highlight:: rest + +:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs +================================================= + +.. module:: sphinx.ext.graphviz + :synopsis: Support for Graphviz graphs. + +.. versionadded:: 0.6 + +This extension allows you to embed `Graphviz <https://graphviz.org/>`_ graphs in +your documents. + +It adds these directives: + +.. rst:directive:: graphviz + + Directive to embed graphviz code. The input code for ``dot`` is given as the + content. For example:: + + .. graphviz:: + + digraph foo { + "bar" -> "baz"; + } + + In HTML output, the code will be rendered to a PNG or SVG image (see + :confval:`graphviz_output_format`). In LaTeX output, the code will be + rendered to an embeddable PDF file. + + You can also embed external dot files, by giving the file name as an + argument to :rst:dir:`graphviz` and no additional content:: + + .. graphviz:: external.dot + + As for all file references in Sphinx, if the filename is absolute, it is + taken as relative to the source directory. + + .. versionchanged:: 1.1 + Added support for external files. + + .. rubric:: options + + .. rst:directive:option:: alt: alternate text + :type: text + + The alternate text of the graph. By default, the graph code is used to + the alternate text. + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + The horizontal alignment of the graph. + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + The caption of the graph. + + .. versionadded:: 1.1 + + .. rst:directive:option:: layout: layout type of the graph + :type: text + + The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the + graphviz commands are also allowed. By default, :confval:`graphviz_dot` + is used. + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + The label of the graph. + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +.. rst:directive:: graph + + Directive for embedding a single undirected graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``graph <name> { <content> }``. + + For example:: + + .. graph:: foo + + "bar" -- "baz"; + + .. note:: The graph name is passed unchanged to Graphviz. If it contains + non-alphanumeric characters (e.g. a dash), you will have to double-quote + it. + + .. rubric:: options + + Same as :rst:dir:`graphviz`. + + .. rst:directive:option:: alt: alternate text + :type: text + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: layout: layout type of the graph + :type: text + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +.. rst:directive:: digraph + + Directive for embedding a single directed graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``digraph <name> { <content> }``. + + For example:: + + .. digraph:: foo + + "bar" -> "baz" -> "quux"; + + .. rubric:: options + + Same as :rst:dir:`graphviz`. + + .. rst:directive:option:: alt: alternate text + :type: text + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: layout: layout type of the graph + :type: text + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +There are also these config values: + +.. confval:: graphviz_dot + + The command name with which to invoke ``dot``. The default is ``'dot'``; you + may need to set this to a full path if ``dot`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>` + option should be preferable, like this:: + + sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html + +.. confval:: graphviz_dot_args + + Additional command-line arguments to give to dot, as a list. The default is + an empty list. This is the right place to set global graph, node or edge + attributes via dot's ``-G``, ``-N`` and ``-E`` options. + +.. confval:: graphviz_output_format + + The output format for Graphviz when building HTML files. This must be either + ``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in + order to make the URL links work properly, an appropriate ``target`` + attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the + link in the following graph should work in the svg output: :: + + .. graphviz:: + + digraph example { + a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"]; + b [label="other"]; + a -> b; + } + + .. versionadded:: 1.0 + Previously, output always was PNG. diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst new file mode 100644 index 0000000..837c0b3 --- /dev/null +++ b/doc/usage/extensions/ifconfig.rst @@ -0,0 +1,38 @@ +.. highlight:: rest + +:mod:`sphinx.ext.ifconfig` -- Include content based on configuration +==================================================================== + +.. module:: sphinx.ext.ifconfig + :synopsis: Include documentation content based on configuration values. + +This extension is quite simple, and features only one directive: + +.. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + +.. rst:directive:: ifconfig + + Include content of the directive only if the Python expression given as an + argument is ``True``, evaluated in the namespace of the project's + configuration (that is, all registered variables from :file:`conf.py` are + available). + + For example, one could write :: + + .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc') + + This stuff is only included in the built docs for unstable versions. + + To make a custom config value known to Sphinx, use + :func:`~sphinx.application.Sphinx.add_config_value` in the setup function in + :file:`conf.py`, e.g.:: + + 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). diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst new file mode 100644 index 0000000..b9af22d --- /dev/null +++ b/doc/usage/extensions/imgconverter.rst @@ -0,0 +1,55 @@ +.. _sphinx.ext.imgconverter: + +:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick +=============================================================================== + +.. module:: sphinx.ext.imgconverter + :synopsis: Convert images to appropriate format for builders + +.. versionadded:: 1.6 + +This extension converts images in your document to appropriate format for +builders. For example, it allows you to use SVG images with LaTeX builder. +As a result, you don't mind what image format the builder supports. + +By default the extension uses ImageMagick_ to perform conversions, +and will not work if ImageMagick is not installed. + +.. _ImageMagick: https://www.imagemagick.org + +.. note:: + + ImageMagick rasterizes a SVG image on conversion. As a result, the image + becomes not scalable. To avoid that, please use other image converters like + `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or + ``rsvg-convert``). + +.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter + + +Configuration +------------- + +.. confval:: image_converter + + A path to a conversion command. By default, the imgconverter finds + the command from search paths. + + On Unix platforms, the command :command:`convert` is used by default. + + On Windows, the command :command:`magick` is used by default. + + .. versionchanged:: 3.1 + + Use :command:`magick` command by default on windows + +.. confval:: image_converter_args + + Additional command-line arguments to give to :command:`convert`, as a list. + The default is an empty list ``[]``. + + On Windows, it defaults to ``["convert"]``. + + .. versionchanged:: 3.1 + + Use ``["convert"]`` by default on Windows diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst new file mode 100644 index 0000000..929f2b6 --- /dev/null +++ b/doc/usage/extensions/index.rst @@ -0,0 +1,81 @@ +========== +Extensions +========== + +Since many projects will need special features in their documentation, Sphinx +allows adding "extensions" to the build process, each of which can modify +almost any aspect of document processing. + +This chapter describes the extensions bundled with Sphinx. For the API +documentation on writing your own extension, refer to :ref:`dev-extensions`. + + +.. _builtin-extensions: + +Built-in extensions +------------------- + +These extensions are built in and can be activated by respective entries in the +:confval:`extensions` configuration value: + +.. toctree:: + :maxdepth: 1 + + autodoc + autosectionlabel + autosummary + coverage + doctest + duration + extlinks + githubpages + graphviz + ifconfig + imgconverter + inheritance + intersphinx + linkcode + math + napoleon + todo + viewcode + + +.. _third-party-extensions: + +Third-party extensions +---------------------- + +You can find several extensions contributed by users in the `sphinx-contrib`__ +organization. If you wish to include your extension in this organization, +simply follow the instructions provided in the `github-administration`__ +project. This is optional and there are several extensions hosted elsewhere. +The `awesome-sphinxdoc`__ and `sphinx-extensions`__ projects are both curated +lists of Sphinx packages, and many packages use the +`Framework :: Sphinx :: Extension`__ and +`Framework :: Sphinx :: Theme`__ trove classifiers for Sphinx extensions and +themes, respectively. + +.. __: https://github.com/sphinx-contrib/ +.. __: https://github.com/sphinx-contrib/github-administration +.. __: https://github.com/yoloseem/awesome-sphinxdoc +.. __: https://sphinx-extensions.readthedocs.io/en/latest/ +.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension +.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme + +Where to put your own extensions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extensions local to a project should be put within the project's directory +structure. Set Python's module search path, ``sys.path``, accordingly so that +Sphinx can find them. For example, if your extension ``foo.py`` lies in the +``exts`` subdirectory of the project root, put into :file:`conf.py`:: + + import sys, os + + sys.path.append(os.path.abspath('exts')) + + extensions = ['foo'] + +You can also install extensions anywhere else on ``sys.path``, e.g. in the +``site-packages`` directory. diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst new file mode 100644 index 0000000..33284b5 --- /dev/null +++ b/doc/usage/extensions/inheritance.rst @@ -0,0 +1,174 @@ +.. highlight:: rest + +:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams +===================================================================== + +.. module:: sphinx.ext.inheritance_diagram + :synopsis: Support for displaying inheritance diagrams via graphviz. + +.. versionadded:: 0.6 + +This extension allows you to include inheritance diagrams, rendered via the +:mod:`Graphviz extension <sphinx.ext.graphviz>`. + +It adds this directive: + +.. rst:directive:: inheritance-diagram + + This directive has one or more arguments, each giving a module or class + name. Class names can be unqualified; in that case they are taken to exist + in the currently described module (see :rst:dir:`py:module`). + + For each given class, and each class in each given module, the base classes + are determined. Then, from all classes and their base classes, a graph is + generated which is then rendered via the graphviz extension to a directed + graph. + + This directive supports an option called ``parts`` that, if given, must be an + integer, advising the directive to keep that many dot-separated parts + in the displayed names (from right to left). For example, ``parts=1`` will + only display class names, without the names of the modules that contain + them. + + .. versionchanged:: 2.0 + The value of for ``parts`` can also be negative, indicating how many + parts to drop from the left. For example, if all your class names start + 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. + + You can use ``caption`` option to give a caption to the diagram. + + .. versionchanged:: 1.1 + Added ``private-bases`` option; previously, all bases were always + included. + + .. versionchanged:: 1.5 + Added ``caption`` option + + It also supports a ``top-classes`` option which requires one or more class + names separated by comma. If specified inheritance traversal will stop at the + specified class names. Given the following Python module:: + + """ + A + / \ + B C + / \ / \ + E D F + """ + + class A: + pass + + class B(A): + pass + + class C(A): + pass + + class D(B, C): + pass + + class E(B): + pass + + class F(C): + pass + + If you have specified a module in the inheritance diagram like this:: + + .. inheritance-diagram:: dummy.test + :top-classes: dummy.test.B, dummy.test.C + + any base classes which are ancestors to ``top-classes`` and are also defined + in the same module will be rendered as stand alone nodes. In this example + class A will be rendered as stand alone node in the graph. This is a known + issue due to how this extension works internally. + + If you don't want class A (or any other ancestors) to be visible then specify + only the classes you would like to generate the diagram for like this:: + + .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F + :top-classes: dummy.test.B, dummy.test.C + + .. versionchanged:: 1.7 + Added ``top-classes`` option to limit the scope of inheritance graphs. + + +Examples +-------- + +The following are different inheritance diagrams for the internal +``InheritanceDiagram`` class that implements the directive. + +With full names:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + + +Showing class names only:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +Stopping the diagram at :class:`sphinx.util.docutils.SphinxDirective` (the +highest superclass still part of Sphinx), and dropping the common left-most +part (``sphinx``) from all names:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :top-classes: sphinx.util.docutils.SphinxDirective + :parts: -1 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :top-classes: sphinx.util.docutils.SphinxDirective + :parts: -1 + +.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :no-contents-entry: + :no-index-entry: + + The internal class that implements the ``inheritance-diagram`` directive. + + +Configuration +------------- + +.. confval:: inheritance_graph_attrs + + A dictionary of graphviz graph attributes for inheritance diagrams. + + For example:: + + inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"', + fontsize=14, ratio='compress') + +.. confval:: inheritance_node_attrs + + A dictionary of graphviz node attributes for inheritance diagrams. + + For example:: + + inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75, + color='dodgerblue1', style='filled') + +.. confval:: inheritance_edge_attrs + + A dictionary of graphviz edge attributes for inheritance diagrams. + +.. confval:: inheritance_alias + + Allows mapping the full qualified name of the class to custom values + (useful when exposing the underlying path of a class is not desirable, + e.g. it's a private class and should not be instantiated by the user). + + For example:: + + inheritance_alias = {'_pytest.Magic': 'pytest.Magic'} diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst new file mode 100644 index 0000000..5aaaf9f --- /dev/null +++ b/doc/usage/extensions/intersphinx.rst @@ -0,0 +1,250 @@ +:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation +====================================================================== + +.. module:: sphinx.ext.intersphinx + :synopsis: Link to other Sphinx documentation. + +.. index:: pair: automatic; linking + +.. versionadded:: 0.5 + +This extension can generate links to the documentation of objects in external +projects, either explicitly through the :rst:role:`external` role, or as a +fallback resolution for any other cross-reference. + +Usage for fallback resolution is simple: whenever Sphinx encounters a +cross-reference that has no matching target in the current documentation set, +it looks for targets in the external documentation sets configured in +:confval:`intersphinx_mapping`. A reference like +``:py:class:`zipfile.ZipFile``` can then link to the Python documentation +for the ZipFile class, without you having to specify where it is located +exactly. + +When using the :rst:role:`external` role, you can force lookup to any external +projects, and optionally to a specific external project. +A link like ``:external:ref:`comparison manual <comparisons>``` will then link +to the label "comparisons" in whichever configured external project, if it +exists, +and a link like ``:external+python:ref:`comparison manual <comparisons>``` will +link to the label "comparisons" only in the doc set "python", if it exists. + +Behind the scenes, this works as follows: + +* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains + a mapping from object names to URIs relative to the HTML set's root. + +* Projects using the Intersphinx extension can specify the location of such + mapping files in the :confval:`intersphinx_mapping` config value. The mapping + will then be used to resolve both :rst:role:`external` references, and also + otherwise missing references to objects into links to the other documentation. + +* By default, the mapping file is assumed to be at the same location as the rest + of the documentation; however, the location of the mapping file can also be + specified individually, e.g. if the docs should be buildable without Internet + access. + + +Configuration +------------- + +To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your +:confval:`extensions` config value, and use these config values to activate +linking: + +.. confval:: intersphinx_mapping + + This config value contains the locations and names of other projects that + should be linked to in this documentation. + + Relative local paths for target locations are taken as relative to the base + of the built documentation, while relative local paths for inventory + locations are taken as relative to the source directory. + + When fetching remote inventory files, proxy settings will be read from + the ``$HTTP_PROXY`` environment variable. + + **Format** + + .. versionadded:: 1.0 + + A dictionary mapping unique identifiers to a tuple ``(target, inventory)``. + Each ``target`` is the base URI of a foreign Sphinx documentation set and can + be a local path or an HTTP URI. The ``inventory`` indicates where the + inventory file can be found: it can be ``None`` (an :file:`objects.inv` file + at the same location as the base URI) or another local file path or a full + HTTP URI to an inventory file. + + The unique identifier can be used in the :rst:role:`external` role, so that + it is clear which intersphinx set the target belongs to. A link like + ``external:python+ref:`comparison manual <comparisons>``` will link to the + label "comparisons" in the doc set "python", if it exists. + + **Example** + + To add links to modules and objects in the Python standard library + documentation, use:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + + This will download the corresponding :file:`objects.inv` file from the + Internet and generate links to the pages under the given URI. The downloaded + inventory is cached in the Sphinx environment, so it must be re-downloaded + whenever you do a full rebuild. + + A second example, showing the meaning of a non-``None`` value of the second + tuple item:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', + 'python-inv.txt')} + + This will read the inventory from :file:`python-inv.txt` in the source + directory, but still generate links to the pages under + ``https://docs.python.org/3``. It is up to you to update the inventory file + as new objects are added to the Python documentation. + + **Multiple targets for the inventory** + + .. versionadded:: 1.3 + + Alternative files can be specified for each inventory. One can give a + tuple for the second inventory tuple item as shown in the following + example. This will read the inventory iterating through the (second) + tuple items until the first successful fetch. The primary use case for + this to specify mirror sites for server downtime of the primary + inventory:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', + (None, 'python-inv.txt'))} + + For a set of books edited and tested locally and then published + together, it could be helpful to try a local inventory file first, + to check references before publication:: + + intersphinx_mapping = { + 'otherbook': + ('https://myproj.readthedocs.io/projects/otherbook/en/latest', + ('../../otherbook/build/html/objects.inv', None)), + } + + **Old format for this config value** + + .. deprecated:: 6.2 + + .. RemovedInSphinx80Warning + + .. caution:: This is the format used before Sphinx 1.0. + It is deprecated and will be removed in Sphinx 8.0. + + A dictionary mapping URIs to either ``None`` or an URI. The keys are the + base URI of the foreign Sphinx documentation sets and can be local paths or + HTTP URIs. The values indicate where the inventory file can be found: they + can be ``None`` (at the same location as the base URI) or another local or + HTTP URI. + + Example: + + .. code:: python + + intersphinx_mapping = {'https://docs.python.org/': None} + + +.. confval:: intersphinx_cache_limit + + The maximum number of days to cache remote inventories. The default is + ``5``, meaning five days. Set this to a negative value to cache inventories + for unlimited time. + +.. confval:: intersphinx_timeout + + The number of seconds for timeout. The default is ``None``, meaning do not + timeout. + + .. note:: + + timeout is not a time limit on the entire response download; rather, an + exception is raised if the server has not issued a response for timeout + seconds. + +.. confval:: intersphinx_disabled_reftypes + + .. versionadded:: 4.3 + + .. versionchanged:: 5.0 + + Changed default value from an empty list to ``['std:doc']``. + + A list of strings being either: + + - the name of a specific reference type in a domain, + e.g., ``std:doc``, ``py:func``, or ``cpp:class``, + - the name of a domain, and a wildcard, e.g., + ``std:*``, ``py:*``, or ``cpp:*``, or + - simply a wildcard ``*``. + + The default value is ``['std:doc']``. + + When a non-:rst:role:`external` cross-reference is being resolved by + intersphinx, skip resolution if it matches one of the specifications in this + list. + + For example, with ``intersphinx_disabled_reftypes = ['std:doc']`` + a cross-reference ``:doc:`installation``` will not be attempted to be + resolved by intersphinx, but ``:external+otherbook:doc:`installation``` will + be attempted to be resolved in the inventory named ``otherbook`` in + :confval:`intersphinx_mapping`. + At the same time, all cross-references generated in, e.g., Python, + declarations will still be attempted to be resolved by intersphinx. + + If ``*`` is in the list of domains, then no non-:rst:role:`external` + references will be resolved by intersphinx. + +Explicitly Reference External Objects +------------------------------------- + +The Intersphinx extension provides the following role. + +.. rst:role:: external + + .. versionadded:: 4.4 + + Use Intersphinx to perform lookup only in external projects, and not the + current project. Intersphinx still needs to know the type of object you + would like to find, so the general form of this role is to write the + cross-refererence as if the object is in the current project, but then prefix + it with ``:external``. + The two forms are then + + - ``:external:domain:reftype:`target```, + e.g., ``:external:py:class:`zipfile.ZipFile```, or + - ``:external:reftype:`target```, + e.g., ``:external:doc:`installation```. + + If you would like to constrain the lookup to a specific external project, + then the key of the project, as specified in :confval:`intersphinx_mapping`, + is added as well to get the two forms + + - ``:external+invname:domain:reftype:`target```, + e.g., ``:external+python:py:class:`zipfile.ZipFile```, or + - ``:external+invname:reftype:`target```, + e.g., ``:external+python:doc:`installation```. + +Showing all links of an Intersphinx mapping file +------------------------------------------------ + +To show all Intersphinx links and their targets of an Intersphinx mapping file, +run ``python -msphinx.ext.intersphinx url-or-path``. This is helpful when +searching for the root cause of a broken Intersphinx link in a documentation +project. The following example prints the Intersphinx mapping of the Python 3 +documentation:: + + $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv + +Using Intersphinx with inventory file under Basic Authorization +--------------------------------------------------------------- + +Intersphinx supports Basic Authorization like this:: + + intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3', + None)} + +The user and password will be stripped from the URL when generating the links. diff --git a/doc/usage/extensions/linkcode.rst b/doc/usage/extensions/linkcode.rst new file mode 100644 index 0000000..e65a0b7 --- /dev/null +++ b/doc/usage/extensions/linkcode.rst @@ -0,0 +1,51 @@ +:mod:`sphinx.ext.linkcode` -- Add external links to source code +=============================================================== + +.. module:: sphinx.ext.linkcode + :synopsis: Add external links to source code. +.. moduleauthor:: Pauli Virtanen + +.. versionadded:: 1.2 + +This extension looks at your object descriptions (``.. class::``, +``.. function::`` etc.) and adds external links to code hosted +somewhere on the web. The intent is similar to the +``sphinx.ext.viewcode`` extension, but assumes the source code can be +found somewhere on the Internet. + +In your configuration, you need to specify a :confval:`linkcode_resolve` +function that returns an URL based on the object. + + +Configuration +------------- + +.. confval:: linkcode_resolve + + This is a function ``linkcode_resolve(domain, info)``, + which should return the URL to source code corresponding to + the object in given domain with given information. + + The function should return ``None`` if no link is to be added. + + The argument ``domain`` specifies the language domain the object is + in. ``info`` is a dictionary with the following keys guaranteed to + be present (dependent on the domain): + + - ``py``: ``module`` (name of the module), ``fullname`` (name of the object) + - ``c``: ``names`` (list of names for the object) + - ``cpp``: ``names`` (list of names for the object) + - ``javascript``: ``object`` (name of the object), ``fullname`` + (name of the item) + + Example: + + .. code-block:: python + + def linkcode_resolve(domain, info): + if domain != 'py': + return None + if not info['module']: + return None + filename = info['module'].replace('.', '/') + return "https://somesite/sourcerepo/%s.py" % filename diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst new file mode 100644 index 0000000..df4fc6b --- /dev/null +++ b/doc/usage/extensions/math.rst @@ -0,0 +1,320 @@ +.. highlight:: rest + +.. _math-support: + +Math support for HTML outputs in Sphinx +======================================= + +.. module:: sphinx.ext.mathbase + :synopsis: Common math support for imgmath and mathjax / jsmath. + +.. versionadded:: 0.5 +.. versionchanged:: 1.8 + + Math support for non-HTML builders is integrated to sphinx-core. + So mathbase extension is no longer needed. + +Since mathematical notation isn't natively supported by HTML in any way, Sphinx +gives a math support to HTML document with several extensions. These use the +reStructuredText math :rst:dir:`directive <math>` and :rst:role:`role <math>`. + +:mod:`sphinx.ext.imgmath` -- Render math as images +-------------------------------------------------- + +.. module:: sphinx.ext.imgmath + :synopsis: Render math as PNG or SVG images. + +.. versionadded:: 1.4 + +This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG +images. This of course means that the computer where the docs are built must +have both programs available. + +There are various configuration values you can set to influence how the images +are built: + +.. confval:: imgmath_image_format + + The output image format. The default is ``'png'``. It should be either + ``'png'`` or ``'svg'``. The image is produced by first executing ``latex`` + on the TeX mathematical mark-up then (depending on the requested format) + either `dvipng`_ or `dvisvgm`_. + +.. confval:: imgmath_use_preview + + ``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the + "depth" of the rendered math: an inline image should use this "depth" in a + ``vertical-align`` style to get correctly aligned with surrounding text. + + This mechanism requires the `LaTeX preview package`_ (available as + ``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this + option is ``False`` but it is strongly recommended to set it to ``True``. + + .. versionchanged:: 2.2 + + This option can be used with the ``'svg'`` :confval:`imgmath_image_format`. + +.. confval:: imgmath_add_tooltips + + Default: ``True``. If false, do not add the LaTeX code as an "alt" attribute + for math images. + +.. confval:: imgmath_font_size + + The font size (in ``pt``) of the displayed math. The default value is + ``12``. It must be a positive integer. + +.. confval:: imgmath_latex + + The command name with which to invoke LaTeX. The default is ``'latex'``; you + may need to set this to a full path if ``latex`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>` + option should be preferable, like this:: + + sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html + + This value should only contain the path to the latex executable, not further + arguments; use :confval:`imgmath_latex_args` for that purpose. + + .. hint:: + + To use `OpenType Math fonts`__ with ``unicode-math``, via a custom + :confval:`imgmath_latex_preamble`, you can set :confval:`imgmath_latex` + to ``'dvilualatex'``, but must then set :confval:`imgmath_image_format` + to ``'svg'``. Note: this has only been tested with ``dvisvgm 3.0.3``. + It significantly increases image production duration compared to using + standard ``'latex'`` with traditional TeX math fonts. + + __ https://tex.stackexchange.com/questions/425098/which-opentype-math-fonts-are-available + + + .. hint:: + + Some fancy LaTeX mark-up (an example was reported which used TikZ to add + various decorations to the equation) require multiple runs of the LaTeX + executable. To handle this, set this configuration setting to + ``'latexmk'`` (or a full path to it) as this Perl script reliably + chooses dynamically how many latex runs are needed. + + .. versionchanged:: 6.2.0 + + Using ``'xelatex'`` (or a full path to it) is now supported. But you + must then add ``'-no-pdf'`` to the :confval:`imgmath_latex_args` list of + the command options. The ``'svg'`` :confval:`imgmath_image_format` is + required. Also, you may need the ``dvisvgm`` binary to be relatively + recent (testing was done only with its ``3.0.3`` release). + + .. note:: + + Regarding the previous note, it is currently not supported to use + ``latexmk`` with option ``-xelatex``. + +.. confval:: imgmath_latex_args + + Additional arguments to give to latex, as a list. The default is an empty + list. + +.. confval:: imgmath_latex_preamble + + Additional LaTeX code to put into the preamble of the LaTeX files used to + translate the math snippets. This is left empty by default. Use it + e.g. to add packages which modify the fonts used for math, such as + ``'\\usepackage{newtxsf}'`` for sans-serif fonts, or + ``'\\usepackage{fouriernc}'`` for serif fonts. Indeed, the default LaTeX + math fonts have rather thin glyphs which (in HTML output) often do not + match well with the font for text. + +.. confval:: imgmath_dvipng + + The command name to invoke ``dvipng``. The default is + ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in + the executable search path. This option is only used when + ``imgmath_image_format`` is set to ``'png'``. + +.. confval:: imgmath_dvipng_args + + Additional arguments to give to dvipng, as a list. The default value is + ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the + image a bit darker and larger then it is by default (this compensates + somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a + transparent background. This option is used only when + ``imgmath_image_format`` is ``'png'``. + +.. confval:: imgmath_dvisvgm + + The command name to invoke ``dvisvgm``. The default is + ``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not + in the executable search path. This option is only used when + ``imgmath_image_format`` is ``'svg'``. + +.. confval:: imgmath_dvisvgm_args + + Additional arguments to give to dvisvgm, as a list. The default value is + ``['--no-fonts']``, which means that ``dvisvgm`` will render glyphs as path + elements (cf the `dvisvgm FAQ`_). This option is used only when + ``imgmath_image_format`` is ``'svg'``. + +.. confval:: imgmath_embed + + Default: ``False``. If true, encode LaTeX output images within HTML files + (base64 encoded) and do not save separate png/svg files to disk. + + .. versionadded:: 5.2 + +:mod:`sphinx.ext.mathjax` -- Render math via JavaScript +------------------------------------------------------- + +.. 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 + (see :confval:`mathjax3_config`). + +.. versionadded:: 1.1 + +This extension puts math as-is into the HTML files. The JavaScript package +MathJax_ is then loaded and transforms the LaTeX markup to readable math live in +the browser. + +Because MathJax (and the necessary fonts) is very large, it is not included in +Sphinx but is set to automatically include it from a third-party site. + +.. attention:: + + You should use the math :rst:dir:`directive <math>` and + :rst:role:`role <math>`, not the native MathJax ``$$``, ``\(``, etc. + + +.. confval:: mathjax_path + + The path to the JavaScript file to include in the HTML files in order to load + MathJax. + + The default is the ``https://`` URL that loads the JS files from the + `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://www.jsdelivr.com/ + + __ 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. + + For example, if you put MathJax into the static path of the Sphinx docs, this + value would be ``MathJax/MathJax.js``. If you host more than one Sphinx + documentation set on one server, it is advisable to install MathJax in a + shared location. + + You can also give a full ``https://`` URL different from the CDN URL. + +.. confval:: mathjax_options + + The options to script tag for mathjax. For example, you can set integrity + option with following setting:: + + mathjax_options = { + 'integrity': 'sha384-......', + } + + The default is empty (``{}``). + + .. versionadded:: 1.8 + + .. versionchanged:: 4.4.1 + + Allow to change the loading method (async or defer) of MathJax if "async" + or "defer" key is set. + +.. confval:: mathjax3_config + + The configuration options for MathJax v3 (which is used by default). + The given dictionary is assigned to the JavaScript variable + ``window.MathJax``. + For more information, please read `Configuring MathJax`__. + + __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration + + The default is empty (not configured). + + .. versionadded:: 4.0 + +.. confval:: mathjax2_config + + The configuration options for MathJax v2 (which can be loaded via + :confval:`mathjax_path`). + The value is used as a parameter of ``MathJax.Hub.Config()``. + For more information, please read `Using in-line configuration options`__. + + __ https://docs.mathjax.org/en/v2.7-latest/ + configuration.html#using-in-line-configuration-options + + For example:: + + mathjax2_config = { + 'extensions': ['tex2jax.js'], + 'jax': ['input/TeX', 'output/HTML-CSS'], + } + + The default is empty (not configured). + + .. versionadded:: 4.0 + + :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`. + +.. confval:: mathjax_config + + Former name of :confval:`mathjax2_config`. + + For help converting your old MathJax configuration to to the new + :confval:`mathjax3_config`, see `Converting Your v2 Configuration to v3`__. + + __ https://docs.mathjax.org/en/latest/web/ + configuration.html#converting-your-v2-configuration-to-v3 + + .. versionadded:: 1.8 + + .. versionchanged:: 4.0 + + This has been renamed to :confval:`mathjax2_config`. + :confval:`mathjax_config` is still supported for backwards compatibility. + +:mod:`sphinx.ext.jsmath` -- Render math via JavaScript +------------------------------------------------------ + +.. module:: sphinx.ext.jsmath + :synopsis: Render math using JavaScript via JSMath. + +This extension works just as the MathJax extension does, but uses the older +package jsMath_. It provides this config value: + +.. confval:: jsmath_path + + The path to the JavaScript file to include in the HTML files in order to load + JSMath. There is no default. + + The path can be absolute or relative; if it is relative, it is relative to + the ``_static`` directory of the built docs. + + For example, if you put JSMath into the static path of the Sphinx docs, this + value would be ``jsMath/easy/load.js``. If you host more than one + Sphinx documentation set on one server, it is advisable to install jsMath in + a shared location. + + +.. _dvipng: https://savannah.nongnu.org/projects/dvipng/ +.. _dvisvgm: https://dvisvgm.de/ +.. _dvisvgm FAQ: https://dvisvgm.de/FAQ +.. _MathJax: https://www.mathjax.org/ +.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/ +.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst new file mode 100644 index 0000000..d2391da --- /dev/null +++ b/doc/usage/extensions/napoleon.rst @@ -0,0 +1,574 @@ +:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings +=========================================================================== + +.. module:: sphinx.ext.napoleon + :synopsis: Support for NumPy and Google style docstrings + +.. moduleauthor:: Rob Ruana + +.. versionadded:: 1.3 + +Overview +-------- + +.. highlight:: text + +Are you tired of writing docstrings that look like this:: + + :param path: The path of the file to wrap + :type path: str + :param field_storage: The :class:`FileStorage` instance to wrap + :type field_storage: FileStorage + :param temporary: Whether or not to delete the file when the File + instance is destructed + :type temporary: bool + :returns: A buffered writable file descriptor + :rtype: BufferedFileStorage + +`reStructuredText`_ is great, but it creates visually dense, hard to read +:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten +according to the `Google Python Style Guide`_:: + + Args: + path (str): The path of the file to wrap + field_storage (FileStorage): The :class:`FileStorage` instance to wrap + temporary (bool): Whether or not to delete the file when the File + instance is destructed + + Returns: + BufferedFileStorage: A buffered writable file descriptor + +Much more legible, no? + +Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and +`Google`_ style docstrings - the style recommended by `Khan Academy`_. + +Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style +docstrings and converts them to reStructuredText before Sphinx attempts to +parse them. This happens in an intermediate step while Sphinx is processing +the documentation, so it doesn't modify any of the docstrings in your actual +source code files. + +.. _ReStructuredText: https://docutils.sourceforge.io/rst.html +.. _Google Python Style Guide: + https://google.github.io/styleguide/pyguide.html +.. _Google: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard +.. _Khan Academy: + https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings + +Getting Started +~~~~~~~~~~~~~~~ + +1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs, + enable napoleon in the Sphinx `conf.py` file:: + + # conf.py + + # Add napoleon to the extensions list + extensions = ['sphinx.ext.napoleon'] + +2. Use `sphinx-apidoc` to build your API documentation:: + + $ sphinx-apidoc -f -o docs/source projectdir + + +Docstrings +~~~~~~~~~~ + +Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>` +can find, including docstrings on: ``modules``, ``classes``, ``attributes``, +``methods``, ``functions``, and ``variables``. Inside each docstring, +specially formatted `Sections`_ are parsed and converted to +reStructuredText. + +All standard reStructuredText formatting still works as expected. + + +.. _Sections: + +Docstring Sections +~~~~~~~~~~~~~~~~~~ + +All of the following section headers are supported: + +* ``Args`` *(alias of Parameters)* +* ``Arguments`` *(alias of Parameters)* +* ``Attention`` +* ``Attributes`` +* ``Caution`` +* ``Danger`` +* ``Error`` +* ``Example`` +* ``Examples`` +* ``Hint`` +* ``Important`` +* ``Keyword Args`` *(alias of Keyword Arguments)* +* ``Keyword Arguments`` +* ``Methods`` +* ``Note`` +* ``Notes`` +* ``Other Parameters`` +* ``Parameters`` +* ``Return`` *(alias of Returns)* +* ``Returns`` +* ``Raise`` *(alias of Raises)* +* ``Raises`` +* ``References`` +* ``See Also`` +* ``Tip`` +* ``Todo`` +* ``Warning`` +* ``Warnings`` *(alias of Warning)* +* ``Warn`` *(alias of Warns)* +* ``Warns`` +* ``Yield`` *(alias of Yields)* +* ``Yields`` + +Google vs NumPy +~~~~~~~~~~~~~~~ + +Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The +main difference between the two styles is that Google uses indentation to +separate sections, whereas NumPy uses underlines. + +Google style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + +NumPy style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + bool + Description of return value + + """ + return True + +NumPy style tends to require more vertical space, whereas Google style +tends to use more horizontal space. Google style tends to be easier to +read for short and simple docstrings, whereas NumPy style tends be easier +to read for long and in-depth docstrings. + +The choice between styles is largely aesthetic, but the two styles should +not be mixed. Choose one style for your project and be consistent with it. + +.. seealso:: + + For complete examples: + + * :ref:`example_google` + * :ref:`example_numpy` + + +Type Annotations +~~~~~~~~~~~~~~~~ + +:pep:`484` introduced a standard way to express types in Python code. +This is an alternative to expressing types directly in docstrings. +One benefit of expressing types according to :pep:`484` is that +type checkers and IDEs can take advantage of them for static code +analysis. :pep:`484` was then extended by :pep:`526` which introduced +a similar way to annotate variables (and attributes). + +Google style with Python 3 type annotations:: + + def func(arg1: int, arg2: str) -> bool: + """Summary line. + + Extended description of function. + + Args: + arg1: Description of arg1 + arg2: Description of arg2 + + Returns: + Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1: Description of attr1 + attr2: Description of attr2 + """ + + attr1: int + attr2: str + +Google style with types in docstrings:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1 (int): Description of attr1 + attr2 (str): Description of attr2 + """ + +.. Note:: + `Python 2/3 compatible annotations`_ aren't currently + supported by Sphinx and won't show up in the docs. + +.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code + + +Configuration +------------- + +Listed below are all the settings used by napoleon and their default +values. These settings can be changed in the Sphinx `conf.py` file. Make +sure that "sphinx.ext.napoleon" is enabled in `conf.py`:: + + # conf.py + + # Add any Sphinx extension module names here, as strings + extensions = ['sphinx.ext.napoleon'] + + # Napoleon settings + napoleon_google_docstring = True + napoleon_numpy_docstring = True + napoleon_include_init_with_doc = False + napoleon_include_private_with_doc = False + napoleon_include_special_with_doc = True + napoleon_use_admonition_for_examples = False + napoleon_use_admonition_for_notes = False + napoleon_use_admonition_for_references = False + napoleon_use_ivar = False + napoleon_use_param = True + napoleon_use_rtype = True + napoleon_preprocess_types = False + napoleon_type_aliases = None + napoleon_attr_annotations = True + +.. _Google style: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy style: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + +.. confval:: napoleon_google_docstring + + True to parse `Google style`_ docstrings. False to disable support + for Google style docstrings. *Defaults to True.* + +.. confval:: napoleon_numpy_docstring + + True to parse `NumPy style`_ docstrings. False to disable support + for NumPy style docstrings. *Defaults to True.* + +.. confval:: napoleon_include_init_with_doc + + True to list ``__init___`` docstrings separately from the class + docstring. False to fall back to Sphinx's default behavior, which + considers the ``__init___`` docstring as part of the class + documentation. *Defaults to False.* + + **If True**:: + + def __init__(self): + """ + This will be included in the docs because it has a docstring + """ + + def __init__(self): + # This will NOT be included in the docs + +.. confval:: napoleon_include_private_with_doc + + True to include private members (like ``_membername``) with docstrings + in the documentation. False to fall back to Sphinx's default behavior. + *Defaults to False.* + + **If True**:: + + def _included(self): + """ + This will be included in the docs because it has a docstring + """ + pass + + def _skipped(self): + # This will NOT be included in the docs + pass + +.. confval:: napoleon_include_special_with_doc + + True to include special members (like ``__membername__``) with + docstrings in the documentation. False to fall back to Sphinx's + default behavior. *Defaults to True.* + + **If True**:: + + def __str__(self): + """ + This will be included in the docs because it has a docstring + """ + return unicode(self).encode('utf-8') + + def __unicode__(self): + # This will NOT be included in the docs + return unicode(self.__class__.__name__) + +.. confval:: napoleon_use_admonition_for_examples + + True to use the ``.. admonition::`` directive for the **Example** and + **Examples** sections. False to use the ``.. rubric::`` directive + instead. One may look better than the other depending on what HTML + theme is used. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Example + ------- + This is just a quick example + + **If True**:: + + .. admonition:: Example + + This is just a quick example + + **If False**:: + + .. rubric:: Example + + This is just a quick example + +.. confval:: napoleon_use_admonition_for_notes + + True to use the ``.. admonition::`` directive for **Notes** sections. + False to use the ``.. rubric::`` directive instead. *Defaults to False.* + + .. note:: The singular **Note** section will always be converted to a + ``.. note::`` directive. + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_admonition_for_references + + True to use the ``.. admonition::`` directive for **References** + sections. False to use the ``.. rubric::`` directive instead. + *Defaults to False.* + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_ivar + + True to use the ``:ivar:`` role for instance variables. False to use + the ``.. attribute::`` directive instead. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Attributes + ---------- + attr1 : int + Description of `attr1` + + **If True**:: + + :ivar attr1: Description of `attr1` + :vartype attr1: int + + **If False**:: + + .. attribute:: attr1 + + Description of `attr1` + + :type: int + +.. confval:: napoleon_use_param + + True to use a ``:param:`` role for each function parameter. False to + use a single ``:parameters:`` role for all the parameters. + *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Parameters + ---------- + arg1 : str + Description of `arg1` + arg2 : int, optional + Description of `arg2`, defaults to 0 + + **If True**:: + + :param arg1: Description of `arg1` + :type arg1: str + :param arg2: Description of `arg2`, defaults to 0 + :type arg2: :class:`int`, *optional* + + **If False**:: + + :parameters: * **arg1** (*str*) -- + Description of `arg1` + * **arg2** (*int, optional*) -- + Description of `arg2`, defaults to 0 + +.. confval:: napoleon_use_keyword + + True to use a ``:keyword:`` role for each function keyword argument. + False to use a single ``:keyword arguments:`` role for all the + keywords. + *Defaults to True.* + + This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils, + ``:keyword:`` and ``:param:`` will not be treated the same way - there will + be a separate "Keyword Arguments" section, rendered in the same fashion as + "Parameters" section (type links created if possible) + + .. seealso:: + + :confval:`napoleon_use_param` + +.. confval:: napoleon_use_rtype + + True to use the ``:rtype:`` role for the return type. False to output + the return type inline with the description. *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Returns + ------- + bool + True if successful, False otherwise + + **If True**:: + + :returns: True if successful, False otherwise + :rtype: bool + + **If False**:: + + :returns: *bool* -- True if successful, False otherwise + +.. confval:: napoleon_preprocess_types + + True to convert the type definitions in the docstrings as references. + Defaults to *False*. + + .. versionadded:: 3.2.1 + .. versionchanged:: 3.5 + + Do preprocess the Google style docstrings also. + +.. confval:: napoleon_type_aliases + + A mapping to translate type names to other names or references. Works + only when ``napoleon_use_param = True``. *Defaults to None.* + + With:: + + napoleon_type_aliases = { + "CustomType": "mypackage.CustomType", + "dict-like": ":term:`dict-like <mapping>`", + } + + This `NumPy style`_ snippet:: + + Parameters + ---------- + arg1 : CustomType + Description of `arg1` + arg2 : dict-like + Description of `arg2` + + becomes:: + + :param arg1: Description of `arg1` + :type arg1: mypackage.CustomType + :param arg2: Description of `arg2` + :type arg2: :term:`dict-like <mapping>` + + .. versionadded:: 3.2 + +.. confval:: napoleon_attr_annotations + + True to allow using :pep:`526` attributes annotations in classes. + If an attribute is documented in the docstring without a type and + has an annotation in the class body, that type is used. + + .. versionadded:: 3.4 + +.. confval:: napoleon_custom_sections + + Add a list of custom sections to include, expanding the list of parsed sections. + *Defaults to None.* + + The entries can either be strings or tuples, depending on the intention: + + * To create a custom "generic" section, just pass a string. + * To create an alias for an existing section, pass a tuple containing the + alias name and the original, in that order. + * To create a custom section that displays like the parameters or returns + section, pass a tuple containing the custom section name and a string + value, "params_style" or "returns_style". + + If an entry is just a string, it is interpreted as a header for a generic + section. If the entry is a tuple/list/indexed container, the first entry + is the name of the section, the second is the section key to emulate. If the + second entry value is "params_style" or "returns_style", the custom section + will be displayed like the parameters section or returns section. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + Support ``params_style`` and ``returns_style`` diff --git a/doc/usage/extensions/todo.rst b/doc/usage/extensions/todo.rst new file mode 100644 index 0000000..bf8b922 --- /dev/null +++ b/doc/usage/extensions/todo.rst @@ -0,0 +1,62 @@ +:mod:`sphinx.ext.todo` -- Support for todo items +================================================ + +.. module:: sphinx.ext.todo + :synopsis: Allow inserting todo items into documents. +.. moduleauthor:: Daniel Bültmann + +.. versionadded:: 0.5 + +There are two additional directives when using this extension: + +.. rst:directive:: todo + + Use this directive like, for example, :rst:dir:`note`. + + It will only show up in the output if :confval:`todo_include_todos` is + ``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``. + + +.. rst:directive:: todolist + + This directive is replaced by a list of all todo directives in the whole + documentation, if :confval:`todo_include_todos` is ``True``. + + +These can be configured as seen below. + +Configuration +------------- + +.. confval:: todo_include_todos + + If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, + else they produce nothing. The default is ``False``. + +.. confval:: todo_emit_warnings + + If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries. + The default is ``False``. + + .. versionadded:: 1.5 + +.. confval:: todo_link_only + + If this is ``True``, :rst:dir:`todolist` produce output without file path and + line, The default is ``False``. + + .. versionadded:: 1.4 + +autodoc provides the following an additional event: + +.. event:: todo-defined (app, node) + + .. versionadded:: 1.5 + + Emitted when a todo is defined. *node* is the defined + ``sphinx.ext.todo.todo_node`` node. diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst new file mode 100644 index 0000000..c90d2ba --- /dev/null +++ b/doc/usage/extensions/viewcode.rst @@ -0,0 +1,106 @@ +:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code +================================================================== + +.. module:: sphinx.ext.viewcode + :synopsis: Add links to a highlighted version of the source code. +.. moduleauthor:: Georg Brandl + +.. versionadded:: 1.0 + +This extension looks at your Python object descriptions (``.. class::``, ``.. +function::`` etc.) and tries to find the source files where the objects are +contained. When found, a separate HTML page will be output for each module with +a highlighted version of the source code, and a link will be added to all object +descriptions that leads to the source code of the described object. A link back +from the source to the description will also be inserted. + +.. warning:: + + Basically, ``viewcode`` extension will import the modules being linked to. + If any modules have side effects on import, these will be executed when + ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their + main routine is protected by a ``if __name__ == '__main__'`` condition. + + In addition, if you don't want to import the modules by ``viewcode``, + you can tell the location of the location of source code to ``viewcode`` + using the :event:`viewcode-find-source` event. + + If :confval:`viewcode_follow_imported_members` is enabled, + you will also need to resolve imported attributes + using the :event:`viewcode-follow-imported` event. + +This extension works only on HTML related builders like ``html``, +``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except +``singlehtml``. By default ``epub`` builder doesn't +support this extension (see :confval:`viewcode_enable_epub`). + +Configuration +------------- + +.. confval:: viewcode_follow_imported_members + + If this is ``True``, viewcode extension will emit + :event:`viewcode-follow-imported` event to resolve the name of the module + by other extensions. The default is ``True``. + + .. versionadded:: 1.3 + + .. versionchanged:: 1.8 + Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``. + +.. confval:: viewcode_enable_epub + + If this is ``True``, viewcode extension is also enabled even if you use + epub builders. This extension generates pages outside toctree, but this + is not preferred as epub format. + + Until 1.4.x, this extension is always enabled. If you want to generate + epub as same as 1.4.x, you should set ``True``, but epub format checker's + score becomes worse. + + The default is ``False``. + + .. versionadded:: 1.5 + + .. warning:: + + Not all epub readers support pages generated by viewcode extension. + These readers ignore links to pages are not under toctree. + + Some reader's rendering result are corrupted and + `epubcheck <https://github.com/IDPF/epubcheck>`_'s score + becomes worse even if the reader supports. + +.. confval:: viewcode_line_numbers + + Default: ``False``. + + If set to ``True``, inline line numbers will be added to the highlighted code. + + .. versionadded:: 7.2 + +.. event:: viewcode-find-source (app, modname) + + .. versionadded:: 1.8 + + Find the source code for a module. + An event handler for this event should return + a tuple of the source code itself and a dictionary of tags. + The dictionary maps the name of a class, function, attribute, etc + to a tuple of its type, the start line number, and the end line number. + The type should be one of "class", "def", or "other". + + :param app: The Sphinx application object. + :param modname: The name of the module to find source code for. + +.. event:: viewcode-follow-imported (app, modname, attribute) + + .. versionadded:: 1.8 + + Find the name of the original module for an attribute. + + :param app: The Sphinx application object. + :param modname: The name of the module that the attribute belongs to. + :param attribute: The name of the member to follow. diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000..fd8cdd8 --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,20 @@ +============ +Using Sphinx +============ + +This guide serves to demonstrate how one can get started with Sphinx and covers +everything from installing Sphinx and configuring your first Sphinx project to +using some of the advanced features Sphinx provides out-of-the-box. If you are +looking for guidance on extending Sphinx, refer to :doc:`/development/index`. + +.. toctree:: + :maxdepth: 2 + + restructuredtext/index + markdown + configuration + builders/index + extensions/index + theming + advanced/intl + advanced/websupport/index diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst new file mode 100644 index 0000000..e85603e --- /dev/null +++ b/doc/usage/installation.rst @@ -0,0 +1,282 @@ +================= +Installing Sphinx +================= + +.. contents:: + :depth: 1 + :local: + :backlinks: none + +.. highlight:: console + +Overview +-------- + +Sphinx is written in `Python`__ and supports Python 3.9+. It builds upon the +shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__, +which are installed when Sphinx is installed. + +__ https://docs.python-guide.org/ +__ https://docutils.sourceforge.io/ +__ https://jinja.palletsprojects.com/ + + +Linux +----- + +Debian/Ubuntu +~~~~~~~~~~~~~ + +Install either ``python3-sphinx`` using :command:`apt-get`: + +:: + + $ apt-get install python3-sphinx + +If it not already present, this will install Python for you. + +RHEL, CentOS +~~~~~~~~~~~~ + +Install ``python-sphinx`` using :command:`yum`: + +:: + + $ yum install python-sphinx + +If it not already present, this will install Python for you. + +Other distributions +~~~~~~~~~~~~~~~~~~~ + +Most Linux distributions have Sphinx in their package repositories. Usually +the package is called ``python3-sphinx``, ``python-sphinx`` or ``sphinx``. Be +aware that there are at least two other packages with ``sphinx`` in their name: +a speech recognition toolkit (*CMU Sphinx*) and a full-text search database +(*Sphinx search*). + + +macOS +----- + +Sphinx can be installed using `Homebrew`__, `MacPorts`__, or as part of +a Python distribution such as `Anaconda`__. + +__ https://brew.sh/ +__ https://www.macports.org/ +__ https://www.anaconda.com/download/#macos + +Homebrew +~~~~~~~~ + +:: + + $ brew install sphinx-doc + +For more information, refer to the `package overview`__. + +__ https://formulae.brew.sh/formula/sphinx-doc + +MacPorts +~~~~~~~~ + +Install either ``python3x-sphinx`` using :command:`port`: + +:: + + $ sudo port install py39-sphinx + +To set up the executable paths, use the ``port select`` command: + +:: + + $ sudo port select --set python python39 + $ sudo port select --set sphinx py39-sphinx + +For more information, refer to the `package overview`__. + +__ https://www.macports.org/ports.php?by=library&substr=py39-sphinx + +Anaconda +~~~~~~~~ + +:: + + $ conda install sphinx + +Windows +------- + +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 +installed, open the *Command Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`). +Once the command prompt is open, type :command:`python --version` and press +Enter. If Python is installed, you will see the version of Python printed to +the screen. If you do not have Python installed, refer to the `Hitchhikers +Guide to Python's`__ Python on Windows installation guides. You must install +`Python 3`__. + +Once Python is installed, you can install Sphinx using :command:`pip`. Refer +to the :ref:`pip installation instructions <install-pypi>` below for more +information. + +__ https://docs.python-guide.org/ +__ https://docs.python-guide.org/starting/install3/win/ + + +.. _install-pypi: + +Installation from PyPI +---------------------- + +Sphinx packages are published on the `Python Package Index +<https://pypi.org/project/Sphinx/>`_. The preferred tool for installing +packages from *PyPI* is :command:`pip`. This tool is provided with all modern +versions of Python. + +On Linux or MacOS, you should open your terminal and run the following command. + +:: + + $ pip install -U sphinx + +On Windows, you should open *Command Prompt* (:kbd:`⊞Win-r` and type +:command:`cmd`) and run the same command. + +.. code-block:: doscon + + C:\> pip install -U sphinx + +After installation, type :command:`sphinx-build --version` on the command +prompt. If everything worked fine, you will see the version number for the +Sphinx package you just installed. + +Installation from *PyPI* also allows you to install the latest development +release. You will not generally need (or want) to do this, but it can be +useful if you see a possible bug in the latest stable release. To do this, use +the ``--pre`` flag. + +:: + + $ pip install -U --pre sphinx + +Using virtual environments +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When installing Sphinx using pip, +it is highly recommended to use *virtual environments*, +which isolate the installed packages from the system packages, +thus removing the need to use administrator privileges. +To create a virtual environment in the ``.venv`` directory, +use the following command. + +:: + + $ python -m venv .venv + +You can read more about them in the `Python Packaging User Guide`_. + +.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment + +.. warning:: + + Note that in some Linux distributions, such as Debian and Ubuntu, + this might require an extra installation step as follows. + + .. code-block:: console + + $ apt-get install python3-venv + +Docker +------ + +Docker images for Sphinx are published on the `Docker Hub`_. There are two kind +of images: + +- `sphinxdoc/sphinx`_ +- `sphinxdoc/sphinx-latexpdf`_ + +.. _Docker Hub: https://hub.docker.com/ +.. _sphinxdoc/sphinx: https://hub.docker.com/r/sphinxdoc/sphinx +.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/r/sphinxdoc/sphinx-latexpdf + +Former one is used for standard usage of Sphinx, and latter one is mainly used for +PDF builds using LaTeX. Please choose one for your purpose. + +.. note:: + + sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large + (over 2GB!). + +.. hint:: + + 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: + + .. code-block:: console + + $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart + + And you can use the following command to build HTML document: + + .. code-block:: console + + $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html + +For more details, please read `README file`__ of docker images. + +.. __: https://hub.docker.com/r/sphinxdoc/sphinx + + +Installation from source +------------------------ + +You can install Sphinx directly from a clone of the `Git repository`__. This +can be done either by cloning the repo and installing from the local clone, on +simply installing directly via :command:`git`. + +:: + + $ git clone https://github.com/sphinx-doc/sphinx + $ cd sphinx + $ pip install . + +:: + + $ pip install git+https://github.com/sphinx-doc/sphinx + +You can also download a snapshot of the Git repo in either `tar.gz`__ or +`zip`__ format. Once downloaded and extracted, these can be installed with +:command:`pip` as above. + +.. highlight:: default + +__ https://github.com/sphinx-doc/sphinx +__ https://github.com/sphinx-doc/sphinx/archive/master.tar.gz +__ https://github.com/sphinx-doc/sphinx/archive/master.zip diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst new file mode 100644 index 0000000..ac24f8d --- /dev/null +++ b/doc/usage/markdown.rst @@ -0,0 +1,52 @@ +.. highlight:: python + +.. _markdown: + +======== +Markdown +======== + +`Markdown`__ is a lightweight markup language with a simplistic plain text +formatting syntax. It exists in many syntactically different *flavors*. To +support Markdown-based documentation, Sphinx can use `MyST-Parser`__. +MyST-Parser is a Docutils bridge to `markdown-it-py`__, a Python package for +parsing the `CommonMark`__ Markdown flavor. + +__ https://daringfireball.net/projects/markdown/ +__ https://myst-parser.readthedocs.io/en/latest/ +__ https://github.com/executablebooks/markdown-it-py +__ https://commonmark.org/ + +Configuration +------------- + +To configure your Sphinx project for Markdown support, proceed as follows: + +#. Install the Markdown parser *MyST-Parser*:: + + pip install --upgrade myst-parser + +#. Add *myst_parser* to the + :confval:`list of configured extensions <extensions>`:: + + extensions = ['myst_parser'] + + .. note:: + MyST-Parser requires Sphinx 2.1 or newer. + +#. If you want to use Markdown files with extensions other than ``.md``, adjust + the :confval:`source_suffix` variable. The following example configures + Sphinx to parse all files with the extensions ``.md`` and ``.txt`` as + Markdown:: + + source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', + } + +#. You can further configure *MyST-Parser* to allow custom syntax that + standard *CommonMark* doesn't support. Read more in the `MyST-Parser + documentation`__. + +__ https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst new file mode 100644 index 0000000..0773f60 --- /dev/null +++ b/doc/usage/quickstart.rst @@ -0,0 +1,348 @@ +=============== +Getting Started +=============== + +Sphinx is a *documentation generator* or a tool that translates a set of plain +text source files into various output formats, automatically producing +cross-references, indices, etc. That is, if you have a directory containing a +bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown` +documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), +man pages and much more. + +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 +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 +:doc:`installation guide </usage/installation>` followed by the intro to the +default markup format used by Sphinx, :doc:`reStucturedText +</usage/restructuredtext/index>`. + +For a great "introduction" to writing docs in general -- the whys and hows, see +also `Write the docs`__, written by Eric Holscher. + +.. __: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/ + + +Setting up the documentation sources +------------------------------------ + +The root directory of a Sphinx collection of plain-text document sources is +called the :term:`source directory`. This directory also contains the Sphinx +configuration file :file:`conf.py`, where you can configure all aspects of how +Sphinx reads your sources and builds your documentation. [#]_ + +Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a +source directory and creates a default :file:`conf.py` with the most useful +configuration values from a few questions it asks you. To use this, run: + +.. code-block:: console + + $ sphinx-quickstart + + +Defining document structure +--------------------------- + +Let's assume you've run :program:`sphinx-quickstart`. It created a source +directory with :file:`conf.py` and a root document, :file:`index.rst`. The +main function of the :term:`root document` is to serve as a welcome page, and +to contain the root of the "table of contents tree" (or *toctree*). This is one +of the main things that Sphinx adds to reStructuredText, a way to connect +multiple files to a single hierarchy of documents. + +.. sidebar:: reStructuredText directives + + ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece + of markup. Directives can have arguments, options and content. + + *Arguments* are given directly after the double colon following the + directive's name. Each directive decides whether it can have arguments, and + how many. + + *Options* are given after the arguments, in form of a "field list". The + ``maxdepth`` is such an option for the ``toctree`` directive. + + *Content* follows the options or arguments after a blank line. Each + directive decides whether to allow content, and what to do with it. + + A common gotcha with directives is that **the first line of the content must + be indented to the same level as the options are**. + +The ``toctree`` directive initially is empty, and looks like so: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + +You add documents listing them in the *content* of the directive: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + + usage/installation + usage/quickstart + ... + +This is exactly how the ``toctree`` for this documentation looks. The +documents to include are given as :term:`document name`\ s, which in short +means that you leave off the file name extension and use forward slashes +(``/``) as directory separators. + +|more| Read more about :ref:`the toctree directive <toctree-directive>`. + +You can now create the files you listed in the ``toctree`` and add content, and +their section titles will be inserted (up to the ``maxdepth`` level) at the +place where the ``toctree`` directive is placed. Also, Sphinx now knows about +the order and hierarchy of your documents. (They may contain ``toctree`` +directives themselves, which means you can create deeply nested hierarchies if +necessary.) + + +Adding content +-------------- + +In Sphinx source files, you can use most features of standard +:term:`reStructuredText`. There are also several features added by Sphinx. +For example, you can add cross-file references in a portable way (which works +for all output types) using the :rst:role:`ref` role. + +For an example, if you are viewing the HTML version, you can look at the source +for this document -- use the "Show Source" link in the sidebar. + +.. todo:: Update the below link when we add new guides on these. + +|more| See :doc:`/usage/restructuredtext/index` for a more in-depth +introduction to reStructuredText, including markup added by Sphinx. + + +Running the build +----------------- + +Now that you have added some files and content, let's make a first build of the +docs. A build is started with the :program:`sphinx-build` program: + +.. code-block:: console + + $ sphinx-build -b html sourcedir builddir + +where *sourcedir* is the :term:`source directory`, and *builddir* is the +directory in which you want to place the built documentation. +The :option:`-b <sphinx-build -b>` option selects a builder; in this example +Sphinx will build HTML files. + +|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all +options that :program:`sphinx-build` supports. + +However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a +:file:`make.bat` which make life even easier for you. These can be executed by +running :command:`make` with the name of the builder. For example. + +.. code-block:: console + + $ make html + +This will build HTML docs in the build directory you chose. Execute +:command:`make` without an argument to see which targets are available. + +.. admonition:: How do I generate PDF documents? + + ``make latexpdf`` runs the :mod:`LaTeX builder + <sphinx.builders.latex.LaTeXBuilder>` and readily invokes the pdfTeX + toolchain for you. + + +.. todo:: Move this whole section into a guide on rST or directives + +Documenting objects +------------------- + +One of Sphinx's main objectives is easy documentation of :dfn:`objects` (in a +very general sense) in any :dfn:`domain`. A domain is a collection of object +types that belong together, complete with markup to create and reference +descriptions of these objects. + +The most prominent domain is the Python domain. For example, to document +Python's built-in function ``enumerate()``, you would add this to one of your +source files. + +.. code-block:: rst + + .. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +This is rendered like this: + +.. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +The argument of the directive is the :dfn:`signature` of the object you +describe, the content is the documentation for it. Multiple signatures can be +given, each in its own line. + +The Python domain also happens to be the default domain, so you don't need to +prefix the markup with the domain name. + +.. code-block:: rst + + .. function:: enumerate(sequence[, start=0]) + + ... + +does the same job if you keep the default setting for the default domain. + +There are several more directives for documenting other types of Python +objects, for example :rst:dir:`py:class` or :rst:dir:`py:method`. There is +also a cross-referencing :dfn:`role` for each of these object types. This +markup will create a link to the documentation of ``enumerate()``. + +:: + + The :py:func:`enumerate` function can be used for ... + +And here is the proof: A link to :func:`enumerate`. + +Again, the ``py:`` can be left out if the Python domain is the default one. It +doesn't matter which file contains the actual documentation for +``enumerate()``; Sphinx will find it and create a link to it. + +Each domain will have special rules for how the signatures can look like, and +make the formatted output look pretty, or add specific features like links to +parameter types, e.g. in the C/C++ domains. + +|more| See :doc:`/usage/restructuredtext/domains` for all the available domains +and their directives/roles. + + +Basic configuration +------------------- + +Earlier we mentioned that the :file:`conf.py` file controls how Sphinx +processes your documents. In that file, which is executed as a Python source +file, you assign configuration values. For advanced users: since it is +executed by Sphinx, you can do non-trivial tasks in it, like extending +:data:`sys.path` or importing a module to find out the version you are +documenting. + +The config values that you probably want to change are already put into the +:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out +(with standard Python syntax: a ``#`` comments the rest of the line). To +change the default value, remove the hash sign and modify the value. To +customize a config value that is not automatically added by +:program:`sphinx-quickstart`, just add an additional assignment. + +Keep in mind that the file uses Python syntax for strings, numbers, lists and +so on. The file is saved in UTF-8 by default, as indicated by the encoding +declaration in the first line. + +|more| See :doc:`/usage/configuration` for documentation of all available +config values. + + +.. todo:: Move this entire doc to a different section + +Autodoc +------- + +When documenting Python code, it is common to put a lot of documentation in the +source files, in documentation strings. Sphinx supports the inclusion of +docstrings from your modules with an :dfn:`extension` (an extension is a Python +module that provides additional features for Sphinx projects) called *autodoc*. + +In order to use *autodoc*, you need to activate it in :file:`conf.py` by +putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the +:confval:`extensions` config value:: + + extensions = ['sphinx.ext.autodoc'] + +Then, you have a few additional directives at your disposal. For example, to +document the function ``io.open()``, reading its signature and +docstring from the source file, you'd write this:: + + .. autofunction:: io.open + +You can also document whole classes or even modules automatically, using member +options for the auto directives, like :: + + .. automodule:: io + :members: + +*autodoc* needs to import your modules in order to extract the docstrings. +Therefore, you must add the appropriate path to :py:data:`sys.path` in your +:file:`conf.py`. + +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their + main routine is protected by a ``if __name__ == '__main__'`` condition. + +|more| See :mod:`sphinx.ext.autodoc` for the complete description of the +features of autodoc. + + +.. todo:: Move this doc to another section + +Intersphinx +----------- + +Many Sphinx documents including the `Python documentation`_ are published on +the Internet. When you want to make links to such documents from your +documentation, you can do it with :mod:`sphinx.ext.intersphinx`. + +.. _Python documentation: https://docs.python.org/3 + +In order to use intersphinx, you need to activate it in :file:`conf.py` by +putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions` +list and set up the :confval:`intersphinx_mapping` config value. + +For example, to link to ``io.open()`` in the Python library manual, you need to +setup your :confval:`intersphinx_mapping` like:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +And now, you can write a cross-reference like ``:py:func:`io.open```. Any +cross-reference that has no matching target in the current documentation set, +will be looked up in the documentation sets configured in +:confval:`intersphinx_mapping` (this needs access to the URL in order to +download the list of valid targets). Intersphinx also works for some other +:term:`domain`\'s roles including ``:ref:``, however it doesn't work for +``:doc:`` as that is non-domain role. + +|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the +features of intersphinx. + + +More topics to be covered +------------------------- + +- :doc:`Other extensions </usage/extensions/index>`: +- Static files +- :doc:`Selecting a theme </usage/theming>` +- :ref:`Templating <templating>` +- Using extensions +- :ref:`Writing extensions <dev-extensions>` + + +.. rubric:: Footnotes + +.. [#] This is the usual layout. However, :file:`conf.py` can also live in + another directory, the :term:`configuration directory`. Refer to the + :doc:`sphinx-build man page </man/sphinx-build>` for more information. + +.. |more| image:: /_static/more.png + :align: middle + :alt: more info diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst new file mode 100644 index 0000000..cc3c615 --- /dev/null +++ b/doc/usage/restructuredtext/basics.rst @@ -0,0 +1,631 @@ +.. highlight:: rst + +.. _rst-primer: + +======================= +reStructuredText Primer +======================= + +reStructuredText is the default plaintext markup language used by Sphinx. This +section is a brief introduction to reStructuredText (reST) concepts and syntax, +intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. + +.. seealso:: + + The authoritative `reStructuredText User Documentation + <https://docutils.sourceforge.io/rst.html>`_. The "ref" links in this + document link to the description of the individual constructs in the reST + reference. + + +Paragraphs +---------- + +The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST +document. Paragraphs are simply chunks of text separated by one or more blank +lines. As in Python, indentation is significant in reST, so all lines of the +same paragraph must be left-aligned to the same level of indentation. + + +.. _rst-inline-markup: + +Inline markup +------------- + +The standard reST inline markup is quite simple: use + +* one asterisk: ``*text*`` for emphasis (italics), +* two asterisks: ``**text**`` for strong emphasis (boldface), and +* backquotes: ````text```` for code samples. + +If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash. + +Be aware of some restrictions of this markup: + +* it may not be nested, +* content may not start or end with whitespace: ``* text*`` is wrong, +* it must be separated from surrounding text by non-word characters. Use a + backslash escaped space to work around that: ``thisis\ *one*\ word``. + +These restrictions may be lifted in future versions of the docutils. + +It is also possible to replace or expand upon some of this inline markup with +roles. Refer to :ref:`rst-roles-alt` for more information. + + +Lists and Quote-like blocks +--------------------------- + +List markup (:duref:`ref <bullet-lists>`) is natural: just place an asterisk at +the start of a paragraph and indent properly. The same goes for numbered +lists; they can also be autonumbered using a ``#`` sign:: + + * This is a bulleted list. + * It has two items, the second + item uses two lines. + + 1. This is a numbered list. + 2. It has two items too. + + #. This is a numbered list. + #. It has two items too. + +Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:: + + * this is + * a list + + * with a nested list + * and some subitems + + * and here the parent list continues + +Definition lists (:duref:`ref <definition-lists>`) are created as follows:: + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + +Note that the term cannot have more than one line of text. + +Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting +them more than the surrounding paragraphs. + +Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks:: + + | These lines are + | broken exactly like in + | the source file. + +There are also several more special blocks available: + +* field lists (:duref:`ref <field-lists>`, with caveats noted in + :ref:`rst-field-lists`) +* option lists (:duref:`ref <option-lists>`) +* quoted literal blocks (:duref:`ref <quoted-literal-blocks>`) +* doctest blocks (:duref:`ref <doctest-blocks>`) + + +.. _rst-literal-blocks: + +Literal blocks +-------------- + +Literal code blocks (:duref:`ref <literal-blocks>`) are introduced by ending a +paragraph with the special marker ``::``. The literal block must be indented +(and, like all paragraphs, separated from the surrounding ones by blank +lines):: + + This is a normal text paragraph. The next paragraph is a code sample:: + + It is not processed in any way, except + that the indentation is removed. + + It can span multiple lines. + + This is a normal text paragraph again. + +The handling of the ``::`` marker is smart: + +* If it occurs as a paragraph of its own, that paragraph is completely left out + of the document. +* If it is preceded by whitespace, the marker is removed. +* If it is preceded by non-whitespace, the marker is replaced by a single + colon. + +That way, the second sentence in the above example's first paragraph would be +rendered as "The next paragraph is a code sample:". + +Code highlighting can be enabled for these literal blocks on a document-wide +basis using the :rst:dir:`highlight` directive and on a project-wide basis +using the :confval:`highlight_language` configuration option. The +:rst:dir:`code-block` directive can be used to set highlighting on a +block-by-block basis. These directives are discussed later. + + +.. _rst-doctest-blocks: + +Doctest blocks +-------------- + +Doctest blocks (:duref:`ref <doctest-blocks>`) are interactive Python sessions +cut-and-pasted into docstrings. They do not require the +:ref:`literal blocks <rst-literal-blocks>` syntax. The doctest block must end +with a blank line and should *not* end with an unused prompt:: + + >>> 1 + 1 + 2 + +.. _rst-tables: + +Tables +------ + +For *grid tables* (:duref:`ref <grid-tables>`), you have to "paint" the cell +grid yourself. They look like this:: + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | ... | ... | | + +------------------------+------------+----------+----------+ + +*Simple tables* (:duref:`ref <simple-tables>`) are easier to write, but +limited: they must contain more than one row, and the first column cells cannot +contain multiple lines. They look like this:: + + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + +Two more syntaxes are supported: *CSV tables* and *List tables*. They use an +*explicit markup block*. Refer to :ref:`table-directives` for more information. + + +Hyperlinks +---------- + +External links +~~~~~~~~~~~~~~ + +Use ```Link text <https://domain.invalid/>`_`` for inline web links. If the +link text should be the web address, you don't need special markup at all, the +parser finds links and mail addresses in ordinary text. + +.. important:: There must be a space between the link text and the opening \< for the URL. + +You can also separate the link and the target definition (:duref:`ref +<hyperlink-targets>`), like this:: + + This is a paragraph that contains `a link`_. + + .. _a link: https://domain.invalid/ + +Internal links +~~~~~~~~~~~~~~ + +Internal linking is done via a special reST role provided by Sphinx, see the +section on specific markup, :ref:`ref-role`. + + +.. _rst-sections: + +Sections +-------- + +Section headers (:duref:`ref <sections>`) are created by underlining (and +optionally overlining) the section title with a punctuation character, at least +as long as the text:: + + ================= + This is a heading + ================= + +Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, this +convention is used in `Python Developer's Guide for documenting +<https://devguide.python.org/documentation/markup/#sections>`_ which you may +follow: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=`` for sections +* ``-`` for subsections +* ``^`` for subsubsections +* ``"`` for paragraphs + +Of course, you are free to use your own marker characters (see the reST +documentation), and use a deeper nesting level, but keep in mind that most +target formats (HTML, LaTeX) have a limited supported nesting depth. + + +.. _rst-field-lists: + +Field Lists +----------- + +Field lists (:duref:`ref <field-lists>`) are sequences of fields marked up like +this:: + + :fieldname: Field content + +They are commonly used in Python documentation:: + + def my_function(my_arg, my_other_arg): + """A function just for me. + + :param my_arg: The first of my arguments. + :param my_other_arg: The second of my arguments. + + :returns: A message (just for me, of course). + """ + +Sphinx extends standard docutils behavior and intercepts field lists specified +at the beginning of documents. Refer to :doc:`field-lists` for more +information. + + +.. TODO This ref should be 'rst-roles', but that already exists. Rename the +.. other ones + +.. _rst-roles-alt: + +Roles +----- + +A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline +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```. + +Docutils supports the following roles: + +* :durole:`emphasis` -- equivalent of ``*emphasis*`` +* :durole:`strong` -- equivalent of ``**strong**`` +* :durole:`literal` -- equivalent of ````literal```` +* :durole:`subscript` -- subscript text +* :durole:`superscript` -- superscript text +* :durole:`title-reference` -- for titles of books, periodicals, and other + materials + +Refer to :doc:`roles` for roles added by Sphinx. + + +Explicit Markup +--------------- + +"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for +most constructs that need special handling, such as footnotes, +specially-highlighted paragraphs, comments, and generic directives. + +An explicit markup block begins with a line starting with ``..`` followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and +normal paragraphs. This may all sound a bit complicated, but it is intuitive +enough when you write it.) + + +.. _rst-directives: + +Directives +---------- + +A directive (:duref:`ref <directives>`) is a generic block of explicit markup. +Along with roles, it is one of the extension mechanisms of reST, and Sphinx +makes heavy use of it. + +Docutils supports the following directives: + +* Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`, + :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`, + :dudir:`tip`, :dudir:`warning` and the generic + :dudir:`admonition <admonitions>`. (Most themes style only "note" and + "warning" specially.) + +* Images: + + - :dudir:`image` (see also Images_ below) + - :dudir:`figure` (an image with caption and optional legend) + +* Additional body elements: + + - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file + only, table of contents) + - :dudir:`container` (a container with a custom class, useful to generate an + outer ``<div>`` in HTML) + - :dudir:`rubric` (a heading without relation to the document sectioning) + - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements) + - :dudir:`parsed-literal` (literal block that supports inline markup) + - :dudir:`epigraph` (a block quote with optional attribution line) + - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own + class attribute) + - :dudir:`compound <compound-paragraph>` (a compound paragraph) + +* Special tables: + + - :dudir:`table` (a table with title) + - :dudir:`csv-table` (a table generated from comma-separated values) + - :dudir:`list-table` (a table generated from a list of lists) + +* Special directives: + + - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup) + - :dudir:`include` (include reStructuredText from another file) -- in Sphinx, + when given an absolute include file path, this directive takes it as + relative to the source directory + + .. _rstclass: + + - :dudir:`class` (assign a class attribute to the next element) + + .. note:: + + When the default domain contains a ``class`` directive, this directive + will be shadowed. Therefore, Sphinx re-exports it as ``rst-class``. + +* HTML specifics: + + - :dudir:`meta` + (generation of HTML ``<meta>`` tags, see also :ref:`html-meta` below) + - :dudir:`title <metadata-document-title>` (override document title) + +* Influencing markup: + + - :dudir:`default-role` (set a new default role) + - :dudir:`role` (create a new role) + + Since these are only per-file, better use Sphinx's facilities for setting the + :confval:`default_role`. + +.. warning:: + + Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and + :dudir:`footer`. + +Directives added by Sphinx are described in :doc:`directives`. + +Basically, a directive consists of a name, arguments, options and content. +(Keep this terminology in mind, it is used in the next chapter describing +custom directives.) Looking at this example, :: + + .. function:: foo(x) + foo(y, z) + :module: some.module.name + + Return a line of text input from the user. + +``function`` is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option +``module`` (as you can see, options are given in the lines immediately +following the arguments and indicated by the colons). Options must be indented +to the same level as the directive content. + +The directive content follows after a blank line and is indented relative to +the directive start or if options are present, by the same amount as the +options. + +Be careful as the indent is not a fixed number of whitespace, e.g. three, but +any number whitespace. This can be surprising when a fixed indent is used +throughout the document and can make a difference for directives which are +sensitive to whitespace. Compare:: + + .. code-block:: + :caption: A cool example + + The output of this line starts with four spaces. + + .. code-block:: + + The output of this line has no spaces at the beginning. + +In the first code block, the indent for the content was fixated by the option +line to three spaces, consequently the content starts with four spaces. +In the latter the indent was fixed by the content itself to seven spaces, thus +it does not start with a space. + + +Images +------ + +reST supports an image directive (:dudir:`ref <image>`), used like so:: + + .. image:: gnu.png + (options) + +When used within Sphinx, the file name given (here ``gnu.png``) must either be +relative to the source file, or absolute which means that they are relative to +the top source directory. For example, the file ``sketch/spam.rst`` could +refer to the image ``images/spam.png`` as ``../images/spam.png`` or +``/images/spam.png``. + +Sphinx will automatically copy image files over to a subdirectory of the output +directory on building (e.g. the ``_static`` directory for HTML output.) + +Interpretation of image size options (``width`` and ``height``) is as follows: +if the size has no unit or the unit is pixels, the given size will only be +respected for output channels that support pixels. Other units (like ``pt`` for +points) will be used for HTML and LaTeX output (the latter replaces ``pt`` by +``bp`` as this is the TeX unit such that ``72bp=1in``). + +Sphinx extends the standard docutils behavior by allowing an asterisk for the +extension:: + + .. image:: gnu.* + +Sphinx then searches for all images matching the provided pattern and +determines their type. Each builder then chooses the best image out of these +candidates. For instance, if the file name ``gnu.*`` was given and two files +:file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX +builder would choose the former, while the HTML builder would prefer the +latter. Supported image types and choosing priority are defined at +:doc:`/usage/builders/index`. + +Note that image file names should not contain spaces. + +.. versionchanged:: 0.4 + Added the support for file names ending in an asterisk. + +.. versionchanged:: 0.6 + Image paths can now be absolute. + +.. versionchanged:: 1.5 + latex target supports pixels (default is ``96px=1in``). + + +Footnotes +--------- + +For footnotes (:duref:`ref <footnotes>`), use ``[#name]_`` to mark the footnote +location, and add the footnote body at the bottom of the document after a +"Footnotes" rubric heading, like so:: + + Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_ + + .. rubric:: Footnotes + + .. [#f1] Text of the first footnote. + .. [#f2] Text of the second footnote. + +You can also explicitly number the footnotes (``[1]_``) or use auto-numbered +footnotes without names (``[#]_``). + + +Citations +--------- + +Standard reST citations (:duref:`ref <citations>`) are supported, with the +additional feature that they are "global", i.e. all citations can be referenced +from all files. Use them like so:: + + Lorem ipsum [Ref]_ dolor sit amet. + + .. [Ref] Book or article reference, URL or whatever. + +Citation usage is similar to footnote usage, but with a label that is not +numeric or begins with ``#``. + + +Substitutions +------------- + +reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which +are pieces of text and/or markup referred to in the text by ``|name|``. They +are defined like footnotes with explicit markup blocks, like this:: + + .. |name| replace:: replacement *text* + +or this:: + + .. |caution| image:: warning.png + :alt: Warning! + +See the :duref:`reST reference for substitutions <substitution-definitions>` +for details. + +.. index:: ! pair: global; substitutions + +If you want to use some substitutions for all documents, put them into +:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file +and include it into all documents you want to use them in, using the +:dudir:`include` directive. (Be sure to give the include file a file name +extension differing from that of other source files, to avoid Sphinx finding it +as a standalone document.) + +Sphinx defines some default substitutions, see :ref:`default-substitutions`. + + +Comments +-------- + +Every explicit markup block which isn't a valid markup construct (like the +footnotes above) is regarded as a comment (:duref:`ref <comments>`). For +example:: + + .. This is a comment. + +You can indent text after a comment start to form multiline comments:: + + .. + This whole indented block + is a comment. + + Still in the comment. + + +.. _html-meta: + +HTML Metadata +------------- + +The :dudir:`meta` directive allows specifying the HTML +`metadata element`_ of a Sphinx documentation page. For example, the +directive:: + + .. meta:: + :description: The Sphinx documentation builder + :keywords: Sphinx, documentation, builder + +will generate the following HTML output: + +.. code:: html + + <meta name="description" content="The Sphinx documentation builder"> + <meta name="keywords" content="Sphinx, documentation, builder"> + +Also, Sphinx will add the keywords as specified in the meta directive to the +search index. Thereby, the ``lang`` attribute of the meta element is +considered. For example, the directive:: + + .. meta:: + :keywords: backup + :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo + :keywords lang=de: bittediesenkeyfinden + +adds the following words to the search indices of builds with different language +configurations: + +* ``pleasefindthiskey``, ``pleasefindthiskeytoo`` to *English* builds; +* ``bittediesenkeyfinden`` to *German* builds; +* ``backup`` to builds in all languages. + +.. _metadata element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta + + +Source encoding +--------------- + +Since the easiest way to include special characters like em dashes or copyright +signs in reST is to directly write them as Unicode characters, one has to +specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by +default; you can change this with the :confval:`source_encoding` config value. + + +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use a + backslash-escaped space to get around that. See :duref:`the reference + <substitution-definitions>` for the details. + +* **No nested inline markup:** Something like ``*see :func:`foo`*`` is not + possible. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst new file mode 100644 index 0000000..1fd5b66 --- /dev/null +++ b/doc/usage/restructuredtext/directives.rst @@ -0,0 +1,1311 @@ +.. highlight:: rst + +========== +Directives +========== + +:ref:`As previously discussed <rst-directives>`, a directive is a generic block +of explicit markup. While Docutils provides a number of directives, Sphinx +provides many more and uses directives as one of the primary extension +mechanisms. + +See :doc:`/usage/restructuredtext/domains` for roles added by domains. + +.. seealso:: + + Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview + of the directives provided by Docutils. + + +.. _toctree-directive: + +Table of contents +----------------- + +.. index:: pair: table of; contents + +Since reST does not have facilities to interconnect several documents, or split +documents into multiple output files, Sphinx uses a custom directive to add +relations between the single files the documentation is made of, as well as +tables of contents. The ``toctree`` directive is the central element. + +.. note:: + + Simple "inclusion" of one file in another can be done with the + :dudir:`include` directive. + +.. note:: + + To create table of contents for current document (.rst file), use the + standard reST :dudir:`contents directive <table-of-contents>`. + +.. rst:directive:: toctree + + This directive inserts a "TOC tree" at the current location, using the + individual TOCs (including "sub-TOC trees") of the documents given in the + directive body. Relative document names (not beginning with a slash) are + relative to the document the directive occurs in, absolute names are relative + to the source directory. A numeric ``maxdepth`` option may be given to + indicate the depth of the tree; by default, all levels are included. [#]_ + + The representation of "TOC tree" is changed in each output format. The + builders that output multiple files (ex. HTML) treat it as a collection of + hyperlinks. On the other hand, the builders that output a single file (ex. + LaTeX, man page, etc.) replace it with the content of the documents on the + TOC tree. + + Consider this example (taken from the Python docs' library reference index):: + + .. toctree:: + :maxdepth: 2 + + intro + strings + datatypes + numeric + (many more documents listed here) + + This accomplishes two things: + + * Tables of contents from all those documents are inserted, with a maximum + depth of two, that means one nested heading. ``toctree`` directives in + those documents are also taken into account. + * Sphinx knows the relative order of the documents ``intro``, + ``strings`` and so forth, and it knows that they are children of the shown + document, the library index. From this information it generates "next + chapter", "previous chapter" and "parent chapter" links. + + **Entries** + + Document titles in the :rst:dir:`toctree` will be automatically read from the + title of the referenced document. If that isn't what you want, you can + specify an explicit title and target using a similar syntax to reST + hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This + looks like:: + + .. toctree:: + + intro + All about strings <strings> + datatypes + + The second line above will link to the ``strings`` document, but will use the + title "All about strings" instead of the title of the ``strings`` document. + + You can also add external links, by giving an HTTP URL instead of a document + name. + + **Section numbering** + + If you want to have section numbers even in HTML output, give the + **toplevel** toctree a ``numbered`` option. For example:: + + .. toctree:: + :numbered: + + foo + bar + + Numbering then starts at the heading of ``foo``. Sub-toctrees are + automatically numbered (don't give the ``numbered`` flag to those). + + Numbering up to a specific depth is also possible, by giving the depth as a + numeric argument to ``numbered``. + + **Additional options** + + You can use the ``caption`` option to provide a toctree caption and you can + use the ``name`` option to provide an implicit target name that can be + referenced by using :rst:role:`ref`:: + + .. toctree:: + :caption: Table of Contents + :name: mastertoc + + foo + + If you want only the titles of documents in the tree to show up, not other + headings of the same level, you can use the ``titlesonly`` option:: + + .. toctree:: + :titlesonly: + + foo + bar + + You can use "globbing" in toctree directives, by giving the ``glob`` flag + option. All entries are then matched against the list of available + documents, and matches are inserted into the list alphabetically. Example:: + + .. toctree:: + :glob: + + intro* + recipe/* + * + + This includes first all documents whose names start with ``intro``, then all + documents in the ``recipe`` folder, then all remaining documents (except the + one containing the directive, of course.) [#]_ + + The special entry name ``self`` stands for the document containing the + toctree directive. This is useful if you want to generate a "sitemap" from + the toctree. + + You can use the ``reversed`` flag option to reverse the order of the entries + in the list. This can be useful when using the ``glob`` flag option to + reverse the ordering of the files. Example:: + + .. toctree:: + :glob: + :reversed: + + recipe/* + + You can also give a "hidden" option to the directive, like this:: + + .. toctree:: + :hidden: + + doc_1 + doc_2 + + This will still notify Sphinx of the document hierarchy, but not insert links + into the document at the location of the directive -- this makes sense if you + intend to insert these links yourself, in a different style, or in the HTML + sidebar. + + In cases where you want to have only one top-level toctree and hide all other + lower level toctrees you can add the "includehidden" option to the top-level + toctree entry:: + + .. toctree:: + :includehidden: + + doc_1 + doc_2 + + All other toctree entries can then be eliminated by the "hidden" option. + + In the end, all documents in the :term:`source directory` (or subdirectories) + must occur in some ``toctree`` directive; Sphinx will emit a warning if it + finds a file that is not included, because that means that this file will not + be reachable through standard navigation. + + Use :confval:`exclude_patterns` to explicitly exclude documents or + directories from building completely. Use :ref:`the "orphan" metadata + <metadata>` to let a document be built, but notify Sphinx that it is not + reachable via a toctree. + + 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. + + .. versionchanged:: 0.6 + Added "numbered" and "hidden" options as well as external links and + support for "self" references. + + .. versionchanged:: 1.0 + Added "titlesonly" option. + + .. versionchanged:: 1.1 + Added numeric argument to "numbered". + + .. versionchanged:: 1.2 + Added "includehidden" option. + + .. versionchanged:: 1.3 + Added "caption" and "name" option. + +Special names +^^^^^^^^^^^^^ + +Sphinx reserves some document names for its own use; you should not try to +create documents with these names -- it will cause problems. + +The special document names (and pages generated for them) are: + +* ``genindex``, ``modindex``, ``search`` + + These are used for the general index, the Python module index, and the search + page, respectively. + + The general index is populated with entries from modules, all + index-generating :ref:`object descriptions <basic-domain-markup>`, and from + :rst:dir:`index` directives. + + The Python module index contains one entry per :rst:dir:`py:module` + directive. + + The search page contains a form that uses the generated JSON search index and + JavaScript to full-text search the generated documents for search words; it + should work on every major browser that supports modern JavaScript. + +* every name beginning with ``_`` + + Though few such names are currently used by Sphinx, you should not + create documents or document-containing directories with such names. (Using + ``_`` as a prefix for a custom template directory is fine.) + +.. warning:: + + Be careful with unusual characters in filenames. Some formats may interpret + these characters in unexpected ways: + + * Do not use the colon ``:`` for HTML based formats. Links to other parts + may not work. + + * Do not use the plus ``+`` for the ePub format. Some resources may not be + found. + + +Paragraph-level markup +---------------------- + +.. index:: note, warning + pair: changes; in version + +These directives create short paragraphs and can be used inside information +units as well as normal text. + +.. rst:directive:: .. note:: + + An especially important bit of information about an API that a user should be + aware of when using whatever bit of API the note pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. + + Example:: + + .. note:: + + This function is not suitable for sending spam e-mails. + +.. rst:directive:: .. warning:: + + An important bit of information about an API that a user should be very aware + of when using whatever bit of API the warning pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. This differs from :rst:dir:`note` in that it is + recommended over :rst:dir:`note` for information regarding security. + +.. rst:directive:: .. versionadded:: version + + This directive documents the version of the project which added the described + feature to the library or C API. When this applies to an entire module, it + should be placed at the top of the module section before any prose. + + The first argument must be given and is the version in question; you can add + a second argument consisting of a *brief* explanation of the change. + + Example:: + + .. versionadded:: 2.5 + The *spam* parameter. + + Note that there must be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. + +.. rst:directive:: .. versionchanged:: version + + Similar to :rst:dir:`versionadded`, but describes when and what changed in + the named feature in some way (new parameters, changed side effects, etc.). + +.. rst:directive:: .. deprecated:: version + + Similar to :rst:dir:`versionchanged`, but describes when the feature was + deprecated. An explanation can also be given, for example to inform the + reader what should be used instead. Example:: + + .. deprecated:: 3.1 + Use :func:`spam` instead. + +.. rst:directive:: seealso + + Many sections include a list of references to module documentation or + external documents. These lists are created using the :rst:dir:`seealso` + directive. + + The :rst:dir:`seealso` directive is typically placed in a section just before + any subsections. For the HTML output, it is shown boxed off from the main + flow of the text. + + The content of the :rst:dir:`seealso` directive should be a reST definition + list. Example:: + + .. seealso:: + + Module :py:mod:`zipfile` + Documentation of the :py:mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format <http://link>`_ + Documentation for tar archive files, including GNU tar extensions. + + There's also a "short form" allowed that looks like this:: + + .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile` + + .. versionadded:: 0.5 + The short form. + +.. rst:directive:: .. rubric:: title + + This directive creates a paragraph heading that is not used to create a + table of contents node. + + .. note:: + + If the *title* of the rubric is "Footnotes" (or the selected language's + equivalent), this rubric is ignored by the LaTeX writer, since it is + assumed to only contain footnote definitions and therefore would create an + empty heading. + +.. rst:directive:: centered + + This directive creates a centered boldfaced line of text. Use it as + follows:: + + .. centered:: LICENSE AGREEMENT + + .. deprecated:: 1.1 + This presentation-only directive is a legacy from older versions. + Use a :ref:`rst-class <rstclass>` directive instead and add an + appropriate style. + +.. rst:directive:: hlist + + This directive must contain a bullet list. It will transform it into a more + compact list by either distributing more than one item horizontally, or + reducing spacing between items, depending on the builder. + + For builders that support the horizontal distribution, there is a ``columns`` + option that specifies the number of columns; it defaults to 2. Example:: + + .. hlist:: + :columns: 3 + + * A list of + * short items + * that should be + * displayed + * horizontally + + .. versionadded:: 0.6 + + +.. _code-examples: + +Showing code examples +--------------------- + +.. index:: pair: 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 +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 +syntax and which should be styled in the same manner. On the other hand, the +:rst:dir:`code-block` directive makes more sense when you want more fine-tuned +control over the styling of each block or when you have a document containing +code blocks using multiple varied syntaxes. Finally, the +:rst:dir:`literalinclude` directive is useful for including entire code files +in your documentation. + +In all cases, Syntax highlighting is provided by `Pygments +<https://pygments.org>`_. When using literal blocks, this is configured using +any :rst:dir:`highlight` directives in the source file. When a ``highlight`` +directive is encountered, it is used until the next ``highlight`` directive is +encountered. If there is no ``highlight`` directive in the file, the global +highlighting language is used. This defaults to ``python`` but can be +configured using the :confval:`highlight_language` config value. The following +values are supported: + +* ``none`` (no highlighting) +* ``default`` (similar to ``python3`` but with a fallback to ``none`` without + warning highlighting fails; the default when :confval:`highlight_language` + isn't set) +* ``guess`` (let Pygments guess the lexer based on contents, only works with + certain well-recognizable languages) +* ``python`` +* ``rest`` +* ``c`` +* ... and any other `lexer alias that Pygments supports`__ + +If highlighting with the selected language fails (i.e. Pygments emits an +"Error" token), the block is not highlighted in any way. + +.. important:: + + The list of lexer aliases supported is tied to the Pygment version. If you + want to ensure consistent highlighting, you should fix your version of + Pygments. + +__ https://pygments.org/docs/lexers + +.. rst:directive:: .. highlight:: language + + Example:: + + .. highlight:: c + + This language is used until the next ``highlight`` directive is encountered. + As discussed previously, *language* can be any lexer alias supported by + Pygments. + + .. rubric:: options + + .. rst:directive:option:: linenothreshold: threshold + :type: number (optional) + + Enable to generate line numbers for code blocks. + + This option takes an optional number as threshold parameter. If any + threshold given, the directive will produce line numbers only for the code + blocks longer than N lines. If not given, line numbers will be produced + for all of code blocks. + + Example:: + + .. highlight:: python + :linenothreshold: 5 + + .. rst:directive:option:: force + :type: no value + + If given, minor errors on highlighting are ignored. + + .. versionadded:: 2.1 + +.. rst:directive:: .. code-block:: [language] + .. sourcecode:: [language] + + Example:: + + .. code-block:: ruby + + Some Ruby code. + + The directive's alias name :rst:dir:`sourcecode` works as well. This + directive takes a language name as an argument. It can be `any lexer alias + supported by Pygments <https://pygments.org/docs/lexers/>`_. If it is not + given, the setting of :rst:dir:`highlight` directive will be used. If not + set, :confval:`highlight_language` will be used. To display a code example + *inline* within other text, rather than as a separate block, you can use the + :rst:role:`code` role instead. + + .. versionchanged:: 2.0 + The ``language`` argument becomes optional. + + .. rubric:: options + + .. rst:directive:option:: linenos + :type: no value + + Enable to generate line numbers for the code block:: + + .. code-block:: ruby + :linenos: + + Some more Ruby code. + + .. rst:directive:option:: lineno-start: number + :type: number + + Set the first line number of the code block. If present, ``linenos`` + option is also automatically activated:: + + .. code-block:: ruby + :lineno-start: 10 + + Some more Ruby code, with line numbering starting at 10. + + .. versionadded:: 1.3 + + .. rst:directive:option:: emphasize-lines: line numbers + :type: comma separated numbers + + Emphasize particular lines of the code block:: + + .. code-block:: python + :emphasize-lines: 3,5 + + def some_function(): + interesting = False + print 'This line is highlighted.' + print 'This one is not...' + print '...but this one is.' + + .. versionadded:: 1.1 + .. versionchanged:: 1.6.6 + LaTeX supports the ``emphasize-lines`` option. + + .. rst:directive:option: force + :type: no value + + Ignore minor errors on highlighting + + .. versionchanged:: 2.1 + + .. rst:directive:option:: caption: caption of code block + :type: text + + Set a caption to the code block. + + .. versionadded:: 1.3 + + .. rst:directive:option:: name: a label for hyperlink + :type: text + + Define implicit target name that can be referenced by using + :rst:role:`ref`. For example:: + + .. code-block:: python + :caption: this.py + :name: this-py + + print 'Explicit is better than implicit.' + + In order to cross-reference a code-block using either the + :rst:role:`ref` or the :rst:role:`numref` role, it is necessary + that both :strong:`name` and :strong:`caption` be defined. The + argument of :strong:`name` can then be given to :rst:role:`numref` + to generate the cross-reference. Example:: + + See :numref:`this-py` for an example. + + When using :rst:role:`ref`, it is possible to generate a cross-reference + with only :strong:`name` defined, provided an explicit title is + given. Example:: + + See :ref:`this code snippet <this-py>` for an example. + + .. versionadded:: 1.3 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 1.4 + + .. rst:directive:option:: dedent: number + :type: number or no value + + Strip indentation characters from the code block. When number given, + leading N characters are removed. When no argument given, leading spaces + are removed via :func:`textwrap.dedent()`. For example:: + + .. code-block:: ruby + :linenos: + :dedent: 4 + + some ruby code + + .. versionadded:: 1.3 + .. versionchanged:: 3.5 + Support automatic dedent. + + .. rst:directive:option:: force + :type: no value + + If given, minor errors on highlighting are ignored. + + .. versionadded:: 2.1 + +.. rst:directive:: .. literalinclude:: filename + + Longer displays of verbatim text may be included by storing the example text + in an external file containing only plain text. The file may be included + using the ``literalinclude`` directive. [#]_ For example, to include the + Python source file :file:`example.py`, use:: + + .. literalinclude:: example.py + + The file name is usually relative to the current file's path. However, if + it is absolute (starting with ``/``), it is relative to the top source + directory. + + **Additional options** + + Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag + option to switch on line numbers, the ``lineno-start`` option to select the + first line number, the ``emphasize-lines`` option to emphasize particular + lines, the ``name`` option to provide an implicit target name, the + ``dedent`` option to strip indentation characters for the code block, and a + ``language`` option to select a language different from the current file's + standard language. In addition, it supports the ``caption`` option; however, + this can be provided with no argument to use the filename as the caption. + Example with options:: + + .. literalinclude:: example.rb + :language: ruby + :emphasize-lines: 12,15-18 + :linenos: + + Tabs in the input are expanded if you give a ``tab-width`` option with the + desired tab width. + + Include files are assumed to be encoded in the :confval:`source_encoding`. + If the file has a different encoding, you can specify it with the + ``encoding`` option:: + + .. literalinclude:: example.py + :encoding: latin-1 + + The directive also supports including only parts of the file. If it is a + Python module, you can select a class, function or method to include using + the ``pyobject`` option:: + + .. literalinclude:: example.py + :pyobject: Timer.start + + This would only include the code lines belonging to the ``start()`` method + in the ``Timer`` class within the file. + + Alternately, you can specify exactly which lines to include by giving a + ``lines`` option:: + + .. literalinclude:: example.py + :lines: 1,3,5-10,20- + + This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. + + Another way to control which part of the file is included is to use the + ``start-after`` and ``end-before`` options (or only one of them). If + ``start-after`` is given as a string option, only lines that follow the + first line containing that string are included. If ``end-before`` is given + as a string option, only lines that precede the first lines containing that + string are included. The ``start-at`` and ``end-at`` options behave in a + similar way, but the lines containing the matched string are included. + + ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string. + ``start-after``/``start-at`` filter lines before the line that contains + option string (``start-at`` will keep the line). Then ``end-before``/``end-at`` + filter lines after the line that contains option string (``end-at`` will keep + the line and ``end-before`` skip the first line). + + .. note:: + + If you want to select only ``[second-section]`` of ini file like the + following, you can use ``:start-at: [second-section]`` and + ``:end-before: [third-section]``: + + .. code-block:: ini + + [first-section] + + var_in_first=true + + [second-section] + + var_in_second=true + + [third-section] + + var_in_third=true + + Useful cases of these option is working with tag comments. + ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options + keep lines between comments: + + .. code-block:: py + + if __name__ == "__main__": + # [initialize] + app.start(":8000") + # [initialized] + + + When lines have been selected in any of the ways described above, the line + numbers in ``emphasize-lines`` refer to those selected lines, counted + consecutively starting at ``1``. + + When specifying particular parts of a file to display, it can be useful to + display the original line numbers. This can be done using the + ``lineno-match`` option, which is however allowed only when the selection + consists of contiguous lines. + + You can prepend and/or append a line to the included code, using the + ``prepend`` and ``append`` option, respectively. This is useful e.g. for + highlighting PHP code that doesn't include the ``<?php``/``?>`` markers. + + If you want to show the diff of the code, you can specify the old file by + giving a ``diff`` option:: + + .. literalinclude:: example.py + :diff: example.py.orig + + This shows the diff between ``example.py`` and ``example.py.orig`` with + unified diff format. + + A ``force`` option can ignore minor errors on highlighting. + + .. versionchanged:: 0.4.3 + Added the ``encoding`` option. + + .. versionchanged:: 0.6 + Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before`` + options, as well as support for absolute filenames. + + .. versionchanged:: 1.0 + Added the ``prepend``, ``append``, and ``tab-width`` options. + + .. versionchanged:: 1.3 + Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and + ``dedent`` options. + + .. versionchanged:: 1.4 + Added the ``class`` option. + + .. versionchanged:: 1.5 + Added the ``start-at``, and ``end-at`` options. + + .. versionchanged:: 1.6 + With both ``start-after`` and ``lines`` in use, the first line as per + ``start-after`` is considered to be with line number ``1`` for ``lines``. + + .. versionchanged:: 2.1 + Added the ``force`` option. + + .. versionchanged:: 3.5 + Support automatic dedent. + +.. _glossary-directive: + +Glossary +-------- + +.. rst:directive:: .. glossary:: + + This directive must contain a reST definition-list-like markup with terms and + definitions. The definitions will then be referenceable with the + :rst:role:`term` role. Example:: + + .. glossary:: + + environment + A structure where information about all documents under the root is + saved, and used for cross-referencing. The environment is pickled + after the parsing stage, so that successive runs only need to read + and parse new and changed documents. + + source directory + The directory which, including its subdirectories, contains all + source files for one Sphinx project. + + In contrast to regular definition lists, *multiple* terms per entry are + allowed, and inline markup is allowed in terms. You can link to all of the + terms. For example:: + + .. glossary:: + + term 1 + term 2 + Definition of both terms. + + (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:: + + .. glossary:: + + term 1 : A + term 2 : B + Definition of both terms. + + 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. + + 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 + automatically sort the entries alphabetically. + + .. versionchanged:: 1.1 + Now supports multiple terms and inline markup in terms. + + .. versionchanged:: 1.4 + Index key for glossary term should be considered *experimental*. + + .. versionchanged:: 4.4 + In internationalized documentation, the ``:sorted:`` flag sorts + according to translated terms. + +Meta-information markup +----------------------- + +.. rst:directive:: .. sectionauthor:: name <email> + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation and email + address. The domain name portion of the address should be lower case. + Example:: + + .. sectionauthor:: Guido van Rossum <guido@python.org> + + By default, this markup isn't reflected in the output in any way (it helps + keep track of contributions), but you can set the configuration value + :confval:`show_authors` to ``True`` to make them produce a paragraph in the + output. + + +.. rst:directive:: .. codeauthor:: name <email> + + The :rst:dir:`codeauthor` directive, which can appear multiple times, names + the authors of the described code, just like :rst:dir:`sectionauthor` names + the author(s) of a piece of documentation. It too only produces output if + the :confval:`show_authors` configuration value is ``True``. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all object descriptions (like +functions, classes or attributes) like discussed in +:doc:`/usage/restructuredtext/domains`. + +However, there is also explicit markup available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +.. rst:directive:: .. index:: <entries> + + This directive contains one or more index entries. Each entry consists of a + type and a value, separated by a colon. + + For example:: + + .. index:: + single: execution; context + pair: module; __main__ + pair: module; sys + triple: module; search; path + seealso: scope + + The execution context + --------------------- + + ... + + This directive contains five entries, which will be converted to entries in + the generated index which link to the exact location of the index statement + (or, in case of offline media, the corresponding page number). + + Since index directives generate cross-reference targets at their location in + the source, it makes sense to put them *before* the thing they refer to -- + e.g. a heading, as in the example above. + + The possible entry types are: + + single + Creates a single index entry. + Can be made a sub-entry by separating the sub-entry text with a semicolon + (this notation is also used below to describe what entries are created). + Examples: + + .. code:: reStructuredText + + .. index:: single: execution + single: execution; context + + - ``single: execution`` creates an index entry labelled ``execution``. + - ``single: execution; context`` creates an sub-entry of ``execution`` + labelled ``context``. + pair + A shortcut to create two index entries. + The pair of values must be separated by a semicolon. + Example: + + .. code:: reStructuredText + + .. index:: pair: loop; statement + + This would create two index entries; ``loop; statement`` and ``statement; loop``. + triple + A shortcut to create three index entries. + All three values must be separated by a semicolon. + Example: + + .. code:: reStructuredText + + .. index:: triple: module; search; path + + This would create three index entries; ``module; search path``, + ``search; path, module``, and ``path; module search``. + see + A shortcut to create an index entry that refers to another entry. + Example: + + .. code:: reStructuredText + + .. index:: see: entry; other + + This would create an index entry referring from ``entry`` to ``other`` + (i.e. 'entry': See 'other'). + seealso + Like ``see``, but inserts 'see also' instead of 'see'. + module, keyword, operator, object, exception, statement, builtin + These **deprecated** shortcuts all create two index entries. + For example, ``module: hashlib`` creates the entries ``module; hashlib`` + and ``hashlib; module``. + + .. deprecated:: 1.0 + These Python-specific entry types are deprecated. + + .. versionchanged:: 7.1 + Removal version set to Sphinx 9.0. + Using these entry types will now emit warnings with the ``index`` category. + + You can mark up "main" index entries by prefixing them with an exclamation + mark. The references to "main" entries are emphasized in the generated + index. For example, if two pages contain :: + + .. index:: Python + + and one page contains :: + + .. index:: ! Python + + then the backlink to the latter page is emphasized among the three backlinks. + + For index directives containing only "single" entries, there is a shorthand + notation:: + + .. index:: BNF, grammar, syntax, notation + + This creates four index entries. + + .. versionchanged:: 1.1 + Added ``see`` and ``seealso`` types, as well as marking main entries. + + .. rubric:: options + + .. rst:directive:option:: name: a label for hyperlink + :type: text + + Define implicit target name that can be referenced by using + :rst:role:`ref`. For example:: + + .. index:: Python + :name: py-index + + .. versionadded:: 3.0 + +.. rst:role:: index + + While the :rst:dir:`index` directive is a block-level markup and links to the + beginning of the next paragraph, there is also a corresponding role that sets + the link target directly where it is used. + + The content of the role can be a simple phrase, which is then kept in the + text and used as an index entry. It can also be a combination of text and + index entry, styled like with explicit targets of cross-references. In that + case, the "target" part can be a full entry as described for the directive + above. For example:: + + This is a normal reST :index:`paragraph` that contains several + :index:`index entries <pair: index; entry>`. + + .. versionadded:: 1.1 + + +.. _tags: + +Including content based on tags +------------------------------- + +.. rst:directive:: .. only:: <expression> + + Include the content of the directive only if the *expression* is true. The + expression should consist of tags, like this:: + + .. only:: html and draft + + Undefined tags are false, defined tags (via the ``-t`` command-line option or + within :file:`conf.py`, see :ref:`here <conf-tags>`) are true. Boolean + expressions, also using parentheses (like ``html and (latex or draft)``) are + supported. + + The *format* and the *name* of the current builder (``html``, ``latex`` or + ``text``) are always set as a tag [#]_. To make the distinction between + format and name explicit, they are also added with the prefix ``format_`` and + ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, + ``format_html`` and ``builder_epub``. + + These standard tags are set *after* the configuration file is read, so they + are not available there. + + All tags must follow the standard Python identifier syntax as set out in + the `Identifiers and keywords + <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_ + documentation. That is, a tag expression may only consist of tags that + conform to the syntax of Python variables. In ASCII, this consists of the + uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` + and, except for the first character, the digits ``0`` through ``9``. + + .. versionadded:: 0.6 + .. versionchanged:: 1.2 + Added the name of the builder and the prefixes. + + .. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + +.. _table-directives: + +Tables +------ + +Use :ref:`reStructuredText tables <rst-tables>`, i.e. either + +- grid table syntax (:duref:`ref <grid-tables>`), +- simple table syntax (:duref:`ref <simple-tables>`), +- :dudir:`csv-table` syntax, +- or :dudir:`list-table` syntax. + +The :dudir:`table` directive serves as optional wrapper of the *grid* and +*simple* syntaxes. + +They work fine in HTML output, but rendering tables to LaTeX is complex. +Check the :confval:`latex_table_style`. + +.. versionchanged:: 1.6 + Merged cells (multi-row, multi-column, both) from grid tables containing + complex contents such as multiple paragraphs, blockquotes, lists, literal + blocks, will render correctly to LaTeX output. + +.. rst:directive:: .. tabularcolumns:: column spec + + This directive influences only the LaTeX output for the next table in + source. The mandatory argument is a column specification (known as an + "alignment preamble" in LaTeX idiom). Please refer to a LaTeX + documentation, such as the `wiki page`_, for basics of such a column + specification. + + .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables + + .. versionadded:: 0.3 + + .. note:: + + :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table + directives. If both are specified, ``:widths:`` option will be ignored. + + Sphinx will render tables with more than 30 rows with ``longtable``. + Besides the ``l``, ``r``, ``c`` and ``p{width}`` column specifiers, one can + also use ``\X{a}{b}`` (new in version 1.5) which configures the column + width to be a fraction ``a/b`` of the total line width and ``\Y{f}`` (new + in version 1.6) where ``f`` is a decimal: for example ``\Y{0.2}`` means that + the column will occupy ``0.2`` times the line width. + + When this directive is used for a table with at most 30 rows, Sphinx will + render it with ``tabulary``. One can then use specific column types ``L`` + (left), ``R`` (right), ``C`` (centered) and ``J`` (justified). They have + the effect of a ``p{width}`` (i.e. each cell is a LaTeX ``\parbox``) with + the specified internal text alignment and an automatically computed + ``width``. + + .. warning:: + + - Cells that contain list-like elements such as object descriptions, + blockquotes or any kind of lists are not compatible with the ``LRCJ`` + column types. The column type must then be some ``p{width}`` with an + explicit ``width`` (or ``\X{a}{b}`` or ``\Y{f}``). + + - Literal blocks do not work with ``tabulary`` at all. Sphinx will + fall back to ``tabular`` or ``longtable`` environments and generate a + suitable column specification. + +In absence of the :rst:dir:`tabularcolumns` directive, and for a table with at +most 30 rows and no problematic cells as described in the above warning, +Sphinx uses ``tabulary`` and the ``J`` column-type for every column. + +.. versionchanged:: 1.6 + + Formerly, the ``L`` column-type was used (text is flushed-left). To revert + to this, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact + Sphinx uses ``T`` and sets it by default to be an alias of ``J``. + +.. hint:: + + A frequent issue with ``tabulary`` is that columns with little contents + appear to be "squeezed". One can add to the LaTeX preamble for example + ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``, + the ``tabulary`` default of ``10pt`` being too small. + +.. hint:: + + To force usage of the LaTeX ``longtable`` environment pass ``longtable`` as + a ``:class:`` option to :dudir:`table`, :dudir:`csv-table`, or + :dudir:`list-table`. Use :ref:`rst-class <rstclass>` for other tables. + +Math +---- + +The input language for mathematics is LaTeX markup. This is the de-facto +standard for plain-text math notation and has the added advantage that no +further translation is necessary when building LaTeX output. + +Keep in mind that when you put math markup in **Python docstrings** read by +:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes, +or use Python raw strings (``r"raw"``). + +.. rst:directive:: math + + Directive for displayed math (math that takes the whole line for itself). + + The directive supports multiple equations, which should be separated by a + blank line:: + + .. math:: + + (a + b)^2 = a^2 + 2ab + b^2 + + (a - b)^2 = a^2 - 2ab + b^2 + + In addition, each single equation is set within a ``split`` environment, + which means that you can have multiple aligned lines in an equation, + aligned at ``&`` and separated by ``\\``:: + + .. math:: + + (a + b)^2 &= (a + b)(a + b) \\ + &= a^2 + 2ab + b^2 + + For more details, look into the documentation of the `AmSMath LaTeX + package`_. + + When the math is only one line of text, it can also be given as a directive + argument:: + + .. math:: (a + b)^2 = a^2 + 2ab + b^2 + + Normally, equations are not numbered. If you want your equation to get a + number, use the ``label`` option. When given, it selects an internal label + for the equation, by which it can be cross-referenced, and causes an equation + number to be issued. See :rst:role:`eq` for an example. The numbering + style depends on the output format. + + There is also an option ``nowrap`` that prevents any wrapping of the given + math in a math environment. When you give this option, you must make sure + yourself that the math is properly set up. For example:: + + .. math:: + :nowrap: + + \begin{eqnarray} + y & = & ax^2 + bx + c \\ + f(x) & = & x^2 + 2xy + y^2 + \end{eqnarray} + +.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex + +.. seealso:: + + :ref:`math-support` + Rendering options for math with HTML builders. + + :confval:`latex_engine` + Explains how to configure LaTeX builder to support Unicode literals in + math mark-up. + + +Grammar production displays +--------------------------- + +Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive: + +.. rst:directive:: .. productionlist:: [productionGroup] + + This directive is used to enclose a group of productions. Each production + is given on a single line and consists of a name, separated by a colon from + the following definition. If the definition spans multiple lines, each + continuation line must begin with a colon placed at the same column as in + the first line. + Blank lines are not allowed within ``productionlist`` directive arguments. + + The definition can contain token names which are marked as interpreted text + (e.g., "``sum ::= `integer` "+" `integer```") -- this generates + cross-references to the productions of these tokens. Outside of the + production list, you can reference to token productions using + :rst:role:`token`. + + The *productionGroup* argument to :rst:dir:`productionlist` serves to + distinguish different sets of production lists that belong to different + grammars. Multiple production lists with the same *productionGroup* thus + define rules in the same scope. + + Inside of the production list, tokens implicitly refer to productions + from the current group. You can refer to the production of another + grammar by prefixing the token with its group name and a colon, e.g, + "``otherGroup:sum``". If the group of the token should not be shown in + the production, it can be prefixed by a tilde, e.g., + "``~otherGroup:sum``". To refer to a production from an unnamed + grammar, the token should be prefixed by a colon, e.g., "``:sum``". + + Outside of the production list, + if you have given a *productionGroup* argument you must prefix the + token name in the cross-reference with the group name and a colon, + e.g., "``myGroup:sum``" instead of just "``sum``". + If the group should not be shown in the title of the link either + an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"), + or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``"). + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. + +The following is an example taken from the Python Reference Manual:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +.. rubric:: Footnotes + +.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree + directive in the document. + +.. [#] A note on available globbing syntax: you can use the standard shell + constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that + these all don't match slashes. A double star ``**`` can be used to + match any sequence of characters *including* slashes. + +.. [#] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. + +.. [#] For most builders name and format are the same. At the moment only + builders derived from the html builder distinguish between the builder + format and the builder name. + + Note that the current builder tag is not available in ``conf.py``, it is + only available after the builder is initialized. diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst new file mode 100644 index 0000000..729e651 --- /dev/null +++ b/doc/usage/restructuredtext/domains.rst @@ -0,0 +1,2303 @@ +.. highlight:: rst + +======= +Domains +======= + +.. versionadded:: 1.0 + +Originally, Sphinx was conceived for a single project, the documentation of the +Python language. Shortly afterwards, it was made available for everyone as a +documentation tool, but the documentation of Python modules remained deeply +built in -- the most fundamental directives, like ``function``, were designed +for Python objects. Since Sphinx has become somewhat popular, interest +developed in using it for many different purposes: C/C++ projects, JavaScript, +or even reStructuredText markup (like in this documentation). + +While this was always possible, it is now much easier to easily support +documentation of projects using different programming languages or even ones +not supported by the main Sphinx distribution, by providing a **domain** for +every such purpose. + +A domain is a collection of markup (reStructuredText :term:`directive`\ s and +:term:`role`\ s) to describe and link to :term:`object`\ s belonging together, +e.g. elements of a programming language. Directive and role names in a domain +have names like ``domain:name``, e.g. ``py:function``. Domains can also +provide custom indices (like the Python Module Index). + +Having domains means that there are no naming problems when one set of +documentation wants to refer to e.g. C++ and Python classes. It also means +that extensions that support the documentation of whole new languages are much +easier to write. + +This section describes what the domains that are included with Sphinx provide. +The domain API is documented as well, in the section :ref:`domain-api`. + + +.. _basic-domain-markup: + +Basic Markup +------------ + +Most domains provide a number of :dfn:`object description directives`, used to +describe specific objects provided by modules. Each directive requires one or +more signatures to provide basic information about what is being described, and +the content should be the description. + +A domain will typically keep an internal index of all entities to aid +cross-referencing. +Typically it will also add entries in the shown general index. +If you want to suppress the addition of an entry in the shown index, you can +give the directive option flag ``:no-index-entry:``. +If you want to exclude the object description from the table of contents, you +can give the directive option flag ``:no-contents-entry:``. +If you want to typeset an object description, without even making it available +for cross-referencing, you can give the directive option flag ``:no-index:`` +(which implies ``:no-index-entry:``). +If you do not want to typeset anything, you can give the directive option flag +``:no-typesetting:``. This can for example be used to create only a target and +index entry for later reference. +Though, note that not every directive in every domain may support these +options. + +.. versionadded:: 3.2 + The directive option ``noindexentry`` in the Python, C, C++, and Javascript + domains. + +.. versionadded:: 5.2.3 + The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript, + and reStructuredText domains. + +.. versionadded:: 7.2 + The directive option ``no-typesetting`` in the Python, C, C++, Javascript, + and reStructuredText domains. + +.. versionchanged:: 7.2 + + * The directive option ``:noindex:`` was renamed + to ``:no-index:``. + * The directive option ``:noindexentry:`` was renamed + to ``:no-index-entry:``. + * The directive option ``:nocontentsentry:`` was renamed + to ``:no-contents-entry:``. + + The previous names are retained as aliases, + but will be deprecated and removed + in a future version of Sphinx. + +An example using a Python domain directive:: + + .. py:function:: spam(eggs) + ham(eggs) + + Spam or ham the foo. + +This describes the two Python functions ``spam`` and ``ham``. (Note that when +signatures become too long, you can break them if you add a backslash to lines +that are continued in the next line. Example:: + + .. py:function:: filterwarnings(action, message='', category=Warning, \ + module='', lineno=0, append=False) + :no-index: + +(This example also shows how to use the ``:no-index:`` flag.) + +The domains also provide roles that link back to these object descriptions. +For example, to link to one of the functions described in the example above, +you could say :: + + The function :py:func:`spam` does a similar thing. + +As you can see, both directive and role names contain the domain name and the +directive name. + +The directive option ``:no-typesetting:`` can be used to create a target +(and index entry) which can later be referenced +by the roles provided by the domain. +This is particularly useful for literate programming: + +.. code-block:: rst + + .. py:function:: spam(eggs) + :no-typesetting: + + .. code:: + + def spam(eggs): + pass + + The function :py:func:`spam` does nothing. + +.. rubric:: Default Domain + +For documentation describing objects from solely one domain, authors will not +have to state again its name at each directive, role, etc... after +having specified a default. This can be done either via the config +value :confval:`primary_domain` or via this directive: + +.. rst:directive:: .. default-domain:: name + + Select a new default domain. While the :confval:`primary_domain` selects a + global default, this only has an effect within the same file. + +If no other default is selected, the Python domain (named ``py``) is the +default one, mostly for compatibility with documentation written for older +versions of Sphinx. + +Directives and roles that belong to the default domain can be mentioned without +giving the domain name, i.e. :: + + .. function:: pyfunc() + + Describes a Python function. + + Reference to :func:`pyfunc`. + +Cross-referencing syntax +~~~~~~~~~~~~~~~~~~~~~~~~ + +For cross-reference roles provided by domains, the same facilities exist as for +general cross-references. See :ref:`xref-syntax`. + +In short: + +* You may supply an explicit title and reference target: ``:role:`title + <target>``` will refer to *target*, but the link text will be *title*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* If you prefix the content with ``~``, the link text will only be the last + component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. + +.. _python-domain: + +The Python Domain +----------------- + +The Python domain (name **py**) provides the following directives for module +declarations: + +.. rst:directive:: .. py:module:: name + + This directive marks the beginning of the description of a module (or package + submodule, in which case the name should be fully qualified, including the + package name). A description of the module such as the docstring can be + placed in the body of the directive. + + This directive will also cause an entry in the global module index. + + .. versionchanged:: 5.2 + + Module directives support body content. + + .. rubric:: options + + .. rst:directive:option:: platform: platforms + :type: comma separated list + + 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 + + This directive tells Sphinx that the classes, functions etc. documented from + here are in the given module (like :rst:dir:`py:module`), but it will not + create index entries, an entry in the Global Module Index, or a link target + for :rst:role:`py:mod`. This is helpful in situations where documentation + for things in a module is spread over multiple files or sections -- one + location has the :rst:dir:`py:module` directive, the others only + :rst:dir:`py:currentmodule`. + +The following directives are provided for module and class contents: + +.. rst:directive:: .. py:function:: name(parameters) + .. py:function:: name[type parameters](parameters) + + Describes a module-level function. + The signature should include the parameters, + together with optional type parameters, + as given in the Python function definition, see :ref:`signatures`. + For example:: + + .. py:function:: Timer.repeat(repeat=3, number=1_000_000) + .. py:function:: add[T](a: T, b: T) -> T + + For methods you should use :rst:dir:`py:method`. + + The description normally includes information about the parameters required + and how they are used (especially whether mutable objects passed as + parameters are modified), side effects, and possible exceptions. + + This information can (in any ``py`` directive) optionally be given in a + structured form, see :ref:`info-field-lists`. + + .. rubric:: options + + .. rst:directive:option:: async + :type: no value + + Indicate the function is an async function. + + .. 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:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the function's type parameters are emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + +.. rst:directive:: .. py:data:: name + + Describes global data in a module, including both variables and values used + as "defined constants." Class and object attributes are not documented + using this environment. + + .. rubric:: options + + .. rst:directive:option:: type: type of the variable + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: value: initial value of the variable + :type: text + + .. 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:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. rst:directive:: .. py:exception:: name + .. py:exception:: name(parameters) + .. py:exception:: name[type parmeters](parameters) + + Describes an exception class. + The signature can, but need not include parentheses with constructor arguments, + or may optionally include type parameters (see :pep:`695`). + + .. rubric:: options + + .. rst:directive:option:: final + :type: no value + + Indicate the class is a final class. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + See :rst:dir:`py:class:single-line-parameter-list`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + See :rst:dir:`py:class:single-line-type-parameter-list`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. py:class:: name + .. py:class:: name(parameters) + .. py:class:: name[type parmeters](parameters) + + Describes a class. + The signature can optionally include type parameters (see :pep:`695`) + or parentheses with parameters which will be shown as the constructor arguments. + See also :ref:`signatures`. + + Methods and attributes belonging to the class should be placed in this + directive's body. If they are placed outside, the supplied name should + contain the class name so that cross-references still work. Example:: + + .. py:class:: Foo + + .. py:method:: quux() + + -- or -- + + .. py:class:: Bar + + .. py:method:: Bar.quux() + + The first way is the preferred one. + + .. 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 + + Indicate the class is a final class. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the class constructor's arguments will be emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the class type parameters are emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + +.. rst:directive:: .. py:attribute:: name + + Describes an object data attribute. The description should include + information about the type of the data to be expected and whether it may be + changed directly. + + .. rubric:: options + + .. rst:directive:option:: type: type of the attribute + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: value: initial value of the attribute + :type: text + + .. 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:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. 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:: classmethod + :type: no value + + Indicate the property is a classmethod. + + .. versionaddedd: 4.2 + + .. rst:directive:option:: type: type of the property + :type: text + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. rst:directive:: .. py:method:: name(parameters) + .. py:method:: name[type parameters](parameters) + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. See also :ref:`signatures` and + :ref:`info-field-lists`. + + .. rubric:: options + + .. rst:directive:option:: abstractmethod + :type: no value + + Indicate the method is an abstract method. + + .. versionadded:: 2.1 + + .. rst:directive:option:: async + :type: no value + + Indicate the method is an async method. + + .. 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 + + Indicate the method is a class method. + + .. versionadded:: 2.1 + + .. rst:directive:option:: final + :type: no value + + Indicate the class is a final method. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the method's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the method's type parameters are emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.2 + + .. rst:directive:option:: staticmethod + :type: no value + + Indicate the method is a static method. + + .. versionadded:: 2.1 + + +.. rst:directive:: .. py:staticmethod:: name(parameters) + .. py:staticmethod:: name[type parameters](parameters) + + Like :rst:dir:`py:method`, but indicates that the method is a static method. + + .. versionadded:: 0.4 + +.. rst:directive:: .. py:classmethod:: name(parameters) + .. py:classmethod:: name[type parameters](parameters) + + Like :rst:dir:`py:method`, but indicates that the method is a class method. + + .. versionadded:: 0.6 + +.. rst:directive:: .. py:decorator:: name + .. py:decorator:: name(parameters) + .. py:decorator:: name[type parameters](parameters) + + Describes a decorator function. The signature should represent the usage as + a decorator. For example, given the functions + + .. code-block:: python + + def removename(func): + func.__name__ = '' + return func + + def setnewname(name): + def decorator(func): + func.__name__ = name + return func + return decorator + + the descriptions should look like this:: + + .. py:decorator:: removename + + Remove name of the decorated function. + + .. py:decorator:: setnewname(name) + + Set name of the decorated function to *name*. + + (as opposed to ``.. py:decorator:: removename(func)``.) + + There is no ``py:deco`` role to link to a decorator that is marked up with + this directive; rather, use the :rst:role:`py:func` role. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the decorator's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the decorator's type parameters are emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.2 + +.. rst:directive:: .. py:decoratormethod:: name + .. py:decoratormethod:: name(signature) + .. py:decoratormethod:: name[type parameters](signature) + + Same as :rst:dir:`py:decorator`, but for decorators that are methods. + + Refer to a decorator method using the :rst:role:`py:meth` role. + +.. _signatures: + +Python Signatures +~~~~~~~~~~~~~~~~~ + +Signatures of functions, methods and class constructors can be given like they +would be written in Python. + +Default values for optional arguments can be given (but if they contain commas, +they will confuse the signature parser). Python 3-style argument annotations +can also be given as well as return type annotations:: + + .. py:function:: compile(source : string, filename, symbol='file') -> ast object + +For functions with optional parameters that don't have default values +(typically functions implemented in C extension modules without keyword +argument support), you can use brackets to specify the optional parts: + +.. py:function:: compile(source[, filename[, symbol]]) + :no-index: + +It is customary to put the opening bracket before the comma. + +Python 3.12 introduced *type parameters*, which are type variables +declared directly within the class or function definition: + +.. code:: python + + class AnimalList[AnimalT](list[AnimalT]): + ... + + def add[T](a: T, b: T) -> T: + return a + b + +The corresponding reStructuredText documentation would be: + +.. code:: rst + + .. py:class:: AnimalList[AnimalT] + + .. py:function:: add[T](a: T, b: T) -> T + +See :pep:`695` and :pep:`696` for details and the full specification. + +.. _info-field-lists: + +Info field lists +~~~~~~~~~~~~~~~~ + +.. versionadded:: 0.4 +.. versionchanged:: 3.0 + + meta fields are added. + +Inside Python object description directives, reST field lists with these fields +are recognized and formatted nicely: + +* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``: + Description of a parameter. +* ``type``: Type of a parameter. Creates a link if possible. +* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific + exception is raised. +* ``var``, ``ivar``, ``cvar``: Description of a variable. +* ``vartype``: Type of a variable. Creates a link if possible. +* ``returns``, ``return``: Description of the return value. +* ``rtype``: Return type. Creates a link if possible. +* ``meta``: Add metadata to description of the python object. The metadata will + not be shown on output document. For example, ``:meta private:`` indicates + the python object is private member. It is used in + :py:mod:`sphinx.ext.autodoc` for filtering members. + +.. note:: + + In current release, all ``var``, ``ivar`` and ``cvar`` are represented as + "Variable". There is no difference at all. + +The field names must consist of one of these keywords and an argument (except +for ``returns`` and ``rtype``, which do not need an argument). This is best +explained by an example:: + + .. py:function:: send_message(sender, recipient, message_body, [priority=1]) + + Send a message to a recipient + + :param str sender: The person sending the message + :param str recipient: The recipient of the message + :param str message_body: The body of the message + :param priority: The priority of the message, can be a number 1-5 + :type priority: integer or None + :return: the message id + :rtype: int + :raises ValueError: if the message_body exceeds 160 characters + :raises TypeError: if the message_body is not a basestring + +This will render like this: + +.. py:function:: send_message(sender, recipient, message_body, [priority=1]) + :no-index: + + Send a message to a recipient + + :param str sender: The person sending the message + :param str recipient: The recipient of the message + :param str message_body: The body of the message + :param priority: The priority of the message, can be a number 1-5 + :type priority: int or None + :return: the message id + :rtype: int + :raises ValueError: if the message_body exceeds 160 characters + :raises TypeError: if the message_body is not a basestring + +It is also possible to combine parameter type and description, if the type is a +single word, like this:: + + :param int priority: The priority of the message, can be a number 1-5 + +.. versionadded:: 1.5 + +Container types such as lists and dictionaries can be linked automatically +using the following syntax:: + + :type priorities: list(int) + :type priorities: list[int] + :type mapping: dict(str, int) + :type mapping: dict[str, int] + :type point: tuple(float, float) + :type point: tuple[float, float] + +Multiple types in a type field will be linked automatically if separated by the +word "or":: + + :type an_arg: int or None + :vartype a_var: str or int + :rtype: float or str + +.. _python-roles: + +Cross-referencing Python objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found: + +.. rst:role:: py:mod + + Reference a module; a dotted name may be used. This should also be used for + package names. + +.. rst:role:: py:func + + Reference a Python function; dotted names may be used. The role text needs + not include trailing parentheses to enhance readability; they will be added + automatically by Sphinx if the :confval:`add_function_parentheses` config + value is ``True`` (the default). + +.. rst:role:: py:data + + Reference a module-level variable. + +.. rst:role:: py:const + + Reference a "defined" constant. This may be a Python variable that is not + intended to be changed. + +.. rst:role:: py:class + + Reference a class; a dotted name may be used. + +.. rst:role:: py:meth + + Reference a method of an object. The role text can include the type name + and the method name; if it occurs within the description of a type, the type + name can be omitted. A dotted name may be used. + +.. rst:role:: py:attr + + 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. + +.. rst:role:: py:obj + + Reference an object of unspecified type. Useful e.g. as the + :confval:`default_role`. + + .. versionadded:: 0.4 + +The name enclosed in this markup can include a module name and/or a class name. +For example, ``:py:func:`filter``` could refer to a function named ``filter`` +in the current module, or the built-in function of that name. In contrast, +``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the +``foo`` module. + +Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with +a dot, this order is reversed. For example, in the documentation of Python's +:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in +function, while ``:py:func:`.open``` refers to :func:`codecs.open`. + +A similar heuristic is used to determine whether the name is an attribute of +the currently documented class. + +Also, if the name is prefixed with a dot, and no exact match is found, the +target is taken as a suffix and all object names with that suffix are searched. +For example, ``:py:meth:`.TarFile.close``` references the +``tarfile.TarFile.close()`` function, even if the current module is not +``tarfile``. Since this can get ambiguous, if there is more than one possible +match, you will get a warning from Sphinx. + +Note that you can combine the ``~`` and ``.`` prefixes: +``:py:meth:`~.TarFile.close``` will reference the ``tarfile.TarFile.close()`` +method, but the visible link caption will only be ``close()``. + + +.. _c-domain: + +The C Domain +------------ + +The C domain (name **c**) is suited for documentation of C API. + +.. rst:directive:: .. c:member:: declaration + .. c:var:: declaration + + Describes a C struct member or variable. Example signature:: + + .. c:member:: PyObject *PyTypeObject.tp_bases + + The difference between the two directives is only cosmetic. + +.. rst:directive:: .. c:function:: function prototype + + Describes a C function. The signature should be given as in C, e.g.:: + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + Note that you don't have to backslash-escape asterisks in the signature, as + it is not parsed by the reST inliner. + + In the description of a function you can use the following info fields + (see also :ref:`info-field-lists`). + + * ``param``, ``parameter``, ``arg``, ``argument``, + Description of a parameter. + * ``type``: Type of a parameter, + written as if passed to the :rst:role:`c:expr` role. + * ``returns``, ``return``: Description of the return value. + * ``rtype``: Return type, + written as if passed to the :rst:role:`c:expr` role. + * ``retval``, ``retvals``: An alternative to ``returns`` for describing + the result of the function. + + .. versionadded:: 4.3 + The ``retval`` field type. + + For example:: + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + :param type: description of the first parameter. + :param nitems: description of the second parameter. + :returns: a result. + :retval NULL: under some conditions. + :retval NULL: under some other conditions as well. + + which renders as + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + .. + ** for some editors (e.g., vim) to stop bold-highlighting the source + + :param type: description of the first parameter. + :param nitems: description of the second parameter. + :returns: a result. + :retval NULL: under some conditions. + :retval NULL: under some other conditions as well. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`c_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + +.. rst:directive:: .. c:macro:: name + .. c:macro:: name(arg list) + + Describes a C macro, i.e., a C-language ``#define``, without the replacement + text. + + In the description of a macro you can use the same info fields as for the + :rst:dir:`c:function` directive. + + .. versionadded:: 3.0 + The function style variant. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the macro's parameters will be emitted on a single logical + line, overriding :confval:`c_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. c:struct:: name + + Describes a C struct. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:union:: name + + Describes a C union. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:enum:: name + + Describes a C enum. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:enumerator:: name + + Describes a C enumerator. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:type:: typedef-like declaration + .. c:type:: name + + Describes a C type, either as a typedef, or the alias for an unspecified + type. + +.. _c-roles: + +Cross-referencing C constructs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following roles create cross-references to C-language constructs if they +are defined in the documentation: + +.. rst:role:: c:member + c:data + c:var + c:func + c:macro + c:struct + c:union + c:enum + c:enumerator + c:type + + Reference a C declaration, as defined above. + Note that :rst:role:`c:member`, :rst:role:`c:data`, and + :rst:role:`c:var` are equivalent. + + .. versionadded:: 3.0 + The var, struct, union, enum, and enumerator roles. + + +Anonymous Entities +~~~~~~~~~~~~~~~~~~ + +C supports anonymous structs, enums, and unions. +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, +though nested symbols will be found even when omitted. +The ``@...`` name will always be rendered as **[anonymous]** (possibly as a +link). + +Example:: + + .. c:struct:: Data + + .. c:union:: @data + + .. c:var:: int a + + .. c:var:: double b + + Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. + +This will be rendered as: + +.. c:struct:: Data + :no-contents-entry: + :no-index-entry: + + .. c:union:: @data + :no-contents-entry: + :no-index-entry: + + .. c:var:: int a + :no-contents-entry: + :no-index-entry: + + .. c:var:: double b + :no-contents-entry: + :no-index-entry: + +Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. + +.. versionadded:: 3.0 + + +Aliasing Declarations +~~~~~~~~~~~~~~~~~~~~~ + +.. c:namespace-push:: @alias + +Sometimes it may be helpful list declarations elsewhere than their main +documentation, e.g., when creating a synopsis of an interface. +The following directive can be used for this purpose. + +.. rst:directive:: .. c:alias:: name + + Insert one or more alias declarations. Each entity can be specified + as they can in the :rst:role:`c:any` role. + + For example:: + + .. c:var:: int data + .. c:function:: int f(double k) + + .. c:alias:: data + f + + becomes + + .. c:var:: int data + .. c:function:: int f(double k) + + .. c:alias:: data + f + + .. versionadded:: 3.2 + + + .. rubric:: Options + + .. rst:directive:option:: maxdepth: int + + Insert nested declarations as well, up to the total depth given. + Use 0 for infinite depth and 1 for just the mentioned declaration. + Defaults to 1. + + .. versionadded:: 3.3 + + .. rst:directive:option:: noroot + + Skip the mentioned declarations and only render nested declarations. + Requires ``maxdepth`` either 0 or at least 2. + + .. versionadded:: 3.5 + + +.. c:namespace-pop:: + + +Inline Expressions and Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rst:role:: c:expr + c:texpr + + Insert a C expression or type either as inline code (``cpp:expr``) + or inline text (``cpp:texpr``). For example:: + + .. c:var:: int a = 42 + + .. c:function:: int f(int i) + + An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). + + A type: :c:expr:`const Data*` + (or as text :c:texpr:`const Data*`). + + will be rendered as follows: + + .. c:var:: int a = 42 + :no-contents-entry: + :no-index-entry: + + .. c:function:: int f(int i) + :no-contents-entry: + :no-index-entry: + + An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). + + A type: :c:expr:`const Data*` + (or as text :c:texpr:`const Data*`). + + .. versionadded:: 3.0 + + +Namespacing +~~~~~~~~~~~ + +.. versionadded:: 3.1 + +The C language it self does not support namespacing, but it can sometimes be +useful to emulate it in documentation, e.g., to show alternate declarations. +The feature may also be used to document members of structs/unions/enums +separate from their parent declaration. + +The current scope can be changed using three namespace directives. They manage +a stack declarations where ``c:namespace`` resets the stack and changes a given +scope. + +The ``c:namespace-push`` directive changes the scope to a given inner scope +of the current one. + +The ``c:namespace-pop`` directive undoes the most recent +``c:namespace-push`` directive. + +.. rst:directive:: .. c:namespace:: scope specification + + Changes the current scope for the subsequent objects to the given scope, and + resets the namespace directive stack. Note that nested scopes can be + specified by separating with a dot, e.g.:: + + .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct + + All subsequent objects will be defined as if their name were declared with + the scope prepended. The subsequent cross-references will be searched for + starting in the current scope. + + Using ``NULL`` or ``0`` as the scope will change to global scope. + +.. rst:directive:: .. c:namespace-push:: scope specification + + Change the scope relatively to the current scope. For example, after:: + + .. c:namespace:: A.B + + .. c:namespace-push:: C.D + + the current scope will be ``A.B.C.D``. + +.. rst:directive:: .. c:namespace-pop:: + + Undo the previous ``c:namespace-push`` directive (*not* just pop a scope). + For example, after:: + + .. c:namespace:: A.B + + .. c:namespace-push:: C.D + + .. c:namespace-pop:: + + the current scope will be ``A.B`` (*not* ``A.B.C``). + + If no previous ``c:namespace-push`` directive has been used, but only a + ``c:namespace`` directive, then the current scope will be reset to global + scope. That is, ``.. c:namespace:: A.B`` is equivalent to:: + + .. c:namespace:: NULL + + .. c:namespace-push:: A.B + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`c-config`. + + +.. _cpp-domain: + +The C++ Domain +-------------- + +The C++ domain (name **cpp**) supports documenting C++ projects. + +Directives for Declaring Entities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following directives are available. All declarations can start with a +visibility statement (``public``, ``private`` or ``protected``). + +.. rst:directive:: .. cpp:class:: class specifier + .. cpp:struct:: class specifier + + Describe a class/struct, possibly with specification of inheritance, e.g.,:: + + .. cpp:class:: MyClass : public MyBase, MyOtherBase + + The difference between :rst:dir:`cpp:class` and :rst:dir:`cpp:struct` is + only cosmetic: the prefix rendered in the output, and the specifier shown + in the index. + + The class can be directly declared inside a nested scope, e.g.,:: + + .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase + + A class template can be declared:: + + .. cpp:class:: template<typename T, std::size_t N> std::array + + or with a line break:: + + .. cpp:class:: template<typename T, std::size_t N> \ + std::array + + Full and partial template specialisations can be declared:: + + .. cpp:class:: template<> \ + std::array<bool, 256> + + .. cpp:class:: template<typename T> \ + std::array<T, 42> + + .. versionadded:: 2.0 + The :rst:dir:`cpp:struct` directive. + +.. rst:directive:: .. cpp:function:: (member) function prototype + + Describe a function or member function, e.g.,:: + + .. cpp:function:: bool myMethod(int arg1, std::string arg2) + + A function with parameters and types. + + .. cpp:function:: bool myMethod(int, double) + + A function with unnamed parameters. + + .. cpp:function:: const T &MyClass::operator[](std::size_t i) const + + An overload for the indexing operator. + + .. cpp:function:: operator bool() const + + A casting operator. + + .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept + + A constexpr function. + + .. cpp:function:: MyClass::MyClass(const MyClass&) = default + + A copy constructor with default implementation. + + Function templates can also be described:: + + .. cpp:function:: template<typename U> \ + void print(U &&u) + + and function template specialisations:: + + .. cpp:function:: template<> \ + void print(int i) + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`cpp_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. cpp:member:: (member) variable declaration + .. cpp:var:: (member) variable declaration + + Describe a variable or member variable, e.g.,:: + + .. cpp:member:: std::string MyClass::myMember + + .. cpp:var:: std::string MyClass::myOtherMember[N][M] + + .. cpp:member:: int a = 42 + + Variable templates can also be described:: + + .. cpp:member:: template<class T> \ + constexpr T pi = T(3.1415926535897932385) + +.. rst:directive:: .. cpp:type:: typedef declaration + .. cpp:type:: name + .. cpp:type:: type alias declaration + + Describe a type as in a typedef declaration, a type alias declaration, or + simply the name of a type with unspecified type, e.g.,:: + + .. cpp:type:: std::vector<int> MyList + + A typedef-like declaration of a type. + + .. cpp:type:: MyContainer::const_iterator + + Declaration of a type alias with unspecified type. + + .. cpp:type:: MyType = std::unordered_map<int, std::string> + + Declaration of a type alias. + + A type alias can also be templated:: + + .. cpp:type:: template<typename T> \ + MyContainer = std::vector<T> + + The example are rendered as follows. + + .. cpp:type:: std::vector<int> MyList + :no-contents-entry: + :no-index-entry: + + A typedef-like declaration of a type. + + .. cpp:type:: MyContainer::const_iterator + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias with unspecified type. + + .. cpp:type:: MyType = std::unordered_map<int, std::string> + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias. + + .. cpp:type:: template<typename T> \ + MyContainer = std::vector<T> + :no-contents-entry: + :no-index-entry: + +.. rst:directive:: .. cpp:enum:: unscoped enum declaration + .. cpp:enum-struct:: scoped enum declaration + .. cpp:enum-class:: scoped enum declaration + + Describe a (scoped) enum, possibly with the underlying type specified. Any + enumerators declared inside an unscoped enum will be declared both in the + enum scope and in the parent scope. Examples:: + + .. cpp:enum:: MyEnum + + An unscoped enum. + + .. cpp:enum:: MySpecificEnum : long + + An unscoped enum with specified underlying type. + + .. cpp:enum-class:: MyScopedEnum + + A scoped enum. + + .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type + + A scoped enum with non-default visibility, and with a specified + underlying type. + +.. rst:directive:: .. cpp:enumerator:: name + .. cpp:enumerator:: name = constant + + Describe an enumerator, optionally with its value defined, e.g.,:: + + .. cpp:enumerator:: MyEnum::myEnumerator + + .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42 + +.. rst:directive:: .. cpp:union:: name + + Describe a union. + + .. versionadded:: 1.8 + +.. rst:directive:: .. cpp:concept:: template-parameter-list name + + .. warning:: The support for concepts is experimental. It is based on the + current draft standard and the Concepts Technical Specification. + The features may change as they evolve. + + Describe a concept. It must have exactly 1 template parameter list. The name + may be a nested name. Example:: + + .. cpp:concept:: template<typename It> std::Iterator + + Proxy to an element of a notional sequence that can be compared, + indirected, or incremented. + + **Notation** + + .. cpp:var:: It r + + An lvalue. + + **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. + + This will render as follows: + + .. cpp:concept:: template<typename It> std::Iterator + + Proxy to an element of a notional sequence that can be compared, + indirected, or incremented. + + **Notation** + + .. cpp:var:: It r + + An lvalue. + + **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. + + .. versionadded:: 1.5 + + +Options +^^^^^^^ + +Some directives support options: + +- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`. +- ``:tparam-line-spec:``, for templated declarations. + If specified, each template parameter will be rendered on a separate line. + + .. versionadded:: 1.6 + +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``. +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). + +Example:: + + .. cpp:class:: Data + + .. cpp:union:: @data + + .. cpp:var:: int a + + .. cpp:var:: double b + + Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. + +This will be rendered as: + +.. cpp:class:: Data + :no-contents-entry: + :no-index-entry: + + .. cpp:union:: @data + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: int a + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: double b + :no-contents-entry: + :no-index-entry: + +Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. + +.. versionadded:: 1.8 + + +Aliasing Declarations +~~~~~~~~~~~~~~~~~~~~~ + +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 + + Insert one or more alias declarations. Each entity can be specified + as they can in the :rst:role:`cpp:any` role. + If the name of a function is given (as opposed to the complete signature), + then all overloads of the function will be listed. + + For example:: + + .. cpp:alias:: Data::a + overload_example::C::f + + becomes + + .. cpp:alias:: Data::a + overload_example::C::f + + whereas:: + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + becomes + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + .. versionadded:: 2.0 + + + .. rubric:: Options + + .. rst:directive:option:: maxdepth: int + + Insert nested declarations as well, up to the total depth given. + Use 0 for infinite depth and 1 for just the mentioned declaration. + Defaults to 1. + + .. versionadded:: 3.5 + + .. rst:directive:option:: noroot + + Skip the mentioned declarations and only render nested declarations. + Requires ``maxdepth`` either 0 or at least 2. + + .. versionadded:: 3.5 + + +Constrained Templates +~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: The support for concepts is experimental. It is based on the + current draft standard and the Concepts Technical Specification. + The features may change as they evolve. + +.. note:: Sphinx does not currently support ``requires`` clauses. + +Placeholders +^^^^^^^^^^^^ + +Declarations may use the name of a concept to introduce constrained template +parameters, or the keyword ``auto`` to introduce unconstrained template +parameters:: + + .. cpp:function:: void f(auto &&arg) + + A function template with a single unconstrained template parameter. + + .. cpp:function:: void f(std::Iterator it) + + A function template with a single template parameter, constrained by the + Iterator concept. + +Template Introductions +^^^^^^^^^^^^^^^^^^^^^^ + +Simple constrained function or class templates can be declared with a `template +introduction` instead of a template parameter list:: + + .. cpp:function:: std::Iterator{It} void advance(It &it) + + A function template with a template parameter constrained to be an + Iterator. + + .. cpp:class:: std::LessThanComparable{T} MySortedContainer + + A class template with a template parameter constrained to be + LessThanComparable. + +They are rendered as follows. + +.. cpp:function:: std::Iterator{It} void advance(It &it) + :no-contents-entry: + :no-index-entry: + + A function template with a template parameter constrained to be an Iterator. + +.. cpp:class:: std::LessThanComparable{T} MySortedContainer + :no-contents-entry: + :no-index-entry: + + A class template with a template parameter constrained to be + LessThanComparable. + +Note however that no checking is performed with respect to parameter +compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction +even though it would not be valid C++. + +Inline Expressions and Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rst:role:: cpp:expr + cpp:texpr + + Insert a C++ expression or type either as inline code (``cpp:expr``) + or inline text (``cpp:texpr``). For example:: + + .. cpp:var:: int a = 42 + + .. cpp:function:: int f(int i) + + An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). + + A type: :cpp:expr:`const MySortedContainer<int>&` + (or as text :cpp:texpr:`const MySortedContainer<int>&`). + + will be rendered as follows: + + .. cpp:var:: int a = 42 + :no-contents-entry: + :no-index-entry: + + .. cpp:function:: int f(int i) + :no-contents-entry: + :no-index-entry: + + An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). + + A type: :cpp:expr:`const MySortedContainer<int>&` + (or as text :cpp:texpr:`const MySortedContainer<int>&`). + + .. versionadded:: 1.7 + The :rst:role:`cpp:expr` role. + + .. versionadded:: 1.8 + The :rst:role:`cpp:texpr` role. + +Namespacing +~~~~~~~~~~~ + +Declarations in the C++ domain are as default placed in global scope. The +current scope can be changed using three namespace directives. They manage a +stack declarations where ``cpp:namespace`` resets the stack and changes a given +scope. + +The ``cpp:namespace-push`` directive changes the scope to a given inner scope +of the current one. + +The ``cpp:namespace-pop`` directive undoes the most recent +``cpp:namespace-push`` directive. + +.. rst:directive:: .. cpp:namespace:: scope specification + + Changes the current scope for the subsequent objects to the given scope, and + resets the namespace directive stack. Note that the namespace does not need + to correspond to C++ namespaces, but can end in names of classes, e.g.,:: + + .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass + + All subsequent objects will be defined as if their name were declared with + the scope prepended. The subsequent cross-references will be searched for + starting in the current scope. + + Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global + scope. + + A namespace declaration can also be templated, e.g.,:: + + .. cpp:class:: template<typename T> \ + std::vector + + .. cpp:namespace:: template<typename T> std::vector + + .. cpp:function:: std::size_t size() const + + declares ``size`` as a member function of the class template + ``std::vector``. Equivalently this could have been declared using:: + + .. cpp:class:: template<typename T> \ + std::vector + + .. cpp:function:: std::size_t size() const + + or:: + + .. cpp:class:: template<typename T> \ + std::vector + +.. rst:directive:: .. cpp:namespace-push:: scope specification + + Change the scope relatively to the current scope. For example, after:: + + .. cpp:namespace:: A::B + + .. cpp:namespace-push:: C::D + + the current scope will be ``A::B::C::D``. + + .. versionadded:: 1.4 + +.. rst:directive:: .. cpp:namespace-pop:: + + Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope). + For example, after:: + + .. cpp:namespace:: A::B + + .. cpp:namespace-push:: C::D + + .. cpp:namespace-pop:: + + the current scope will be ``A::B`` (*not* ``A::B::C``). + + If no previous ``cpp:namespace-push`` directive has been used, but only a + ``cpp:namespace`` directive, then the current scope will be reset to global + scope. That is, ``.. cpp:namespace:: A::B`` is equivalent to:: + + .. cpp:namespace:: nullptr + + .. cpp:namespace-push:: A::B + + .. versionadded:: 1.4 + +Info field lists +~~~~~~~~~~~~~~~~~ + +All the C++ directives for declaring entities support the following +info fields (see also :ref:`info-field-lists`): + +* ``tparam``: Description of a template parameter. + +The :rst:dir:`cpp:function` directive additionally supports the +following fields: + +* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter. +* ``returns``, ``return``: Description of a return value. +* ``retval``, ``retvals``: An alternative to ``returns`` for describing + the result of the function. +* `throws`, `throw`, `exception`: Description of a possibly thrown exception. + +.. versionadded:: 4.3 + The ``retval`` field type. + +.. _cpp-roles: + +Cross-referencing +~~~~~~~~~~~~~~~~~ + +These roles link to the given declaration types: + +.. rst:role:: cpp:any + cpp:class + cpp:struct + cpp:func + cpp:member + cpp:var + cpp:type + cpp:concept + cpp:enum + cpp:enumerator + + Reference a C++ declaration by name (see below for details). The name must + 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. + +.. admonition:: Note on References with Templates Parameters/Arguments + + These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must + be taken when referencing a (partial) template specialization, e.g. if the + link looks like this: ``:cpp:class:`MyClass<int>```. + This is interpreted as a link to ``int`` with a title of ``MyClass``. + In this case, escape the opening angle bracket with a backslash, + like this: ``:cpp:class:`MyClass\<int>```. + + When a custom title is not needed it may be useful to use the roles for + inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where + angle brackets do not need escaping. + +Declarations without template parameters and template arguments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For linking to non-templated declarations the name must be a nested name, e.g., +``f`` or ``MyClass::f``. + + +Overloaded (member) functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When a (member) function is referenced using just its name, the reference +will point to an arbitrary matching overload. +The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles use an alternative +format, which simply is a complete function declaration. +This will resolve to the exact matching overload. +As example, consider the following class declaration: + +.. cpp:namespace-push:: overload_example +.. cpp:class:: C + + .. cpp:function:: void f(double d) const + .. cpp:function:: void f(double d) + .. cpp:function:: void f(int i) + .. cpp:function:: void f() + +References using the :rst:role:`cpp:func` role: + +- Arbitrary overload: ``C::f``, :cpp:func:`C::f` +- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()` +- 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` + +Note that the :confval:`add_function_parentheses` configuration variable +does not influence specific overload references. + +.. cpp:namespace-pop:: + + +Templated declarations +^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: Wrapper + + .. cpp:class:: template<typename TOuter> \ + Outer + + .. cpp:class:: template<typename TInner> \ + Inner + +In general the reference must include the template parameter declarations, +and template arguments for the prefix of qualified names. For example: + +- ``template\<typename TOuter> Wrapper::Outer`` + (:cpp:class:`template\<typename TOuter> Wrapper::Outer`) +- ``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. + +As a shorthand notation, if a template parameter list is omitted, +then the lookup will assume either a primary template or a non-template, +but not a partial template specialisation. +This means the following references work as well: + +- ``Wrapper::Outer`` + (:cpp:class:`Wrapper::Outer`) +- ``Wrapper::Outer::Inner`` + (:cpp:class:`Wrapper::Outer::Inner`) +- ``template\<typename TInner> Wrapper::Outer::Inner`` + (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`) + +(Full) Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: template<typename TOuter> \ + Outer + + .. cpp:class:: template<typename TInner> \ + Inner + +.. cpp:class:: template<> \ + Outer<int> + + .. cpp:class:: template<typename TInner> \ + Inner + + .. cpp:class:: template<> \ + Inner<bool> + +In general the reference must include a template parameter list for each +template argument list. The full specialisation above can therefore be +referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<> +Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>`` +(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`). As a +shorthand the empty template parameter list can be omitted, e.g., +``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>`` +(:cpp:class:`Outer\<int>::Inner\<bool>`). + +Partial Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declaration. + +.. cpp:class:: template<typename T> \ + Outer<T*> + +References to partial specialisations must always include the template +parameter lists, e.g., ``template\<typename T> Outer\<T*>`` +(:cpp:class:`template\<typename T> Outer\<T*>`). Currently the lookup only +succeed if the template parameter identifiers are equal strings. + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`cpp-config`. + +.. _domains-std: + +The Standard Domain +------------------- + +The so-called "standard" domain collects all markup that doesn't warrant a +domain of its own. Its directives and roles are not prefixed with a domain +name. + +The standard domain is also where custom object descriptions, added using the +:func:`~sphinx.application.Sphinx.add_object_type` API, are placed. + +There is a set of directives allowing documenting command-line programs: + +.. rst:directive:: .. option:: name args, name args, ... + + Describes a command line argument or switch. Option argument names should + be enclosed in angle brackets. Examples:: + + .. option:: dest_dir + + Destination directory. + + .. option:: -m <module>, --module <module> + + Run a module as a script. + + The directive will create cross-reference targets for the given options, + referenceable by :rst:role:`option` (in the example case, you'd use something + like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```). + + .. versionchanged:: 5.3 + + One can cross-reference including an option value: ``:option:`--module=foobar```, + ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```. + + Use :confval:`option_emphasise_placeholders` for parsing of + "variable part" of a literal text (similarly to the :rst:role:`samp` role). + + ``cmdoption`` directive is a deprecated alias for the ``option`` directive. + +.. rst:directive:: .. envvar:: name + + Describes an environment variable that the documented code or program uses + or defines. Referenceable by :rst:role:`envvar`. + +.. rst:directive:: .. program:: name + + Like :rst:dir:`py:currentmodule`, this directive produces no output. + Instead, it serves to notify Sphinx that all following :rst:dir:`option` + directives document options for the program called *name*. + + If you use :rst:dir:`program`, you have to qualify the references in your + :rst:role:`option` roles by the program name, so if you have the following + situation :: + + .. program:: rm + + .. option:: -r + + Work recursively. + + .. program:: svn + + .. option:: -r <revision> + + Specify the revision to work upon. + + then ``:option:`rm -r``` would refer to the first option, while + ``:option:`svn -r``` would refer to the second one. + + If ``None`` is passed to the argument, the directive will reset the + current program name. + + The program name may contain spaces (in case you want to document + subcommands like ``svn add`` and ``svn commit`` separately). + + .. versionadded:: 0.5 + +There is also a very generic object description directive, which is not tied to +any domain: + +.. rst:directive:: .. describe:: text + .. object:: text + + This directive produces the same formatting as the specific ones provided by + domains, but does not create index entries or cross-referencing targets. + Example:: + + .. describe:: PAPER + + You can set this variable to select a paper size. + + +The JavaScript Domain +--------------------- + +The JavaScript domain (name **js**) provides the following directives: + +.. rst:directive:: .. js:module:: name + + This directive sets the module name for object declarations that follow + after. The module name is used in the global module index and in cross + references. This directive does not create an object heading like + :rst:dir:`py:class` would, for example. + + By default, this directive will create a linkable entity and will cause an + entry in the global module index, unless the ``no-index`` option is + specified. If this option is specified, the directive will only update the + current module name. + + .. versionadded:: 1.6 + .. versionchanged:: 5.2 + + Module directives support body content. + +.. rst:directive:: .. js:function:: name(signature) + + Describes a JavaScript function or method. If you want to describe + arguments as optional use square brackets as :ref:`documented <signatures>` + for Python signatures. + + You can use fields to give more details about arguments and their expected + types, errors which may be thrown by the function, and the value being + returned:: + + .. js:function:: $.getJSON(href, callback[, errback]) + + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param errback: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. + + This is rendered as: + + .. js:function:: $.getJSON(href, callback[, errback]) + :no-index: + + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param errback: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:method:: name(signature) + + This directive is an alias for :rst:dir:`js:function`, however it describes + a function that is implemented as a method on a class object. + + .. versionadded:: 1.6 + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:class:: name + + Describes a constructor that creates an object. This is basically like a + function but will show up with a `class` prefix:: + + .. js:class:: MyAnimal(name[, age]) + + :param string name: The name of the animal + :param number age: an optional age for the animal + + This is rendered as: + + .. js:class:: MyAnimal(name[, age]) + :no-index: + + :param string name: The name of the animal + :param number age: an optional age for the animal + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:data:: name + + Describes a global variable or constant. + +.. rst:directive:: .. js:attribute:: object.name + + Describes the attribute *name* of *object*. + +.. _js-roles: + +These roles are provided to refer to the described objects: + +.. rst:role:: js:mod + js:func + js:meth + js:class + js:data + js:attr + + +The reStructuredText domain +--------------------------- + +The reStructuredText domain (name **rst**) provides the following directives: + +.. rst:directive:: .. rst:directive:: name + + Describes a reST directive. The *name* can be a single directive name or + actual directive syntax (`..` prefix and `::` suffix) with arguments that + will be rendered differently. For example:: + + .. rst:directive:: foo + + Foo description. + + .. rst:directive:: .. bar:: baz + + Bar description. + + will be rendered as: + + .. rst:directive:: foo + :no-index: + + Foo description. + + .. rst:directive:: .. bar:: baz + :no-index: + + Bar description. + +.. rst:directive:: .. rst:directive:option:: name + + Describes an option for reST directive. The *name* can be a single option + name or option name with arguments which separated with colon (``:``). + For example:: + + .. rst:directive:: toctree + + .. rst:directive:option:: caption: caption of ToC + + .. rst:directive:option:: glob + + will be rendered as: + + .. rst:directive:: toctree + :no-index: + + .. rst:directive:option:: caption: caption of ToC + :no-index: + + .. rst:directive:option:: glob + :no-index: + + .. rubric:: options + + .. rst:directive:option:: type: description of argument + :type: text + + Describe the type of option value. + + For example:: + + .. rst:directive:: toctree + + .. rst:directive:option:: maxdepth + :type: integer or no value + + .. versionadded:: 2.1 + +.. rst:directive:: .. rst:role:: name + + Describes a reST role. For example:: + + .. rst:role:: foo + + Foo description. + + will be rendered as: + + .. rst:role:: foo + :no-index: + + Foo description. + +.. _rst-roles: + +These roles are provided to refer to the described objects: + +.. rst:role:: rst:dir + rst:role + +.. _math-domain: + +The Math Domain +--------------- + +The math domain (name **math**) provides the following roles: + +.. rst:role:: math:numref + + Role for cross-referencing equations defined by :rst:dir:`math` directive + via their label. Example:: + + .. math:: e^{i\pi} + 1 = 0 + :label: euler + + Euler's identity, equation :math:numref:`euler`, was elected one of the + most beautiful mathematical formulas. + + .. versionadded:: 1.8 + +More domains +------------ + +The sphinx-contrib_ repository contains more domains available as extensions; +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://github.com/sphinx-contrib + +.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/ +.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/ +.. _CoffeeScript: https://pypi.org/project/sphinxcontrib-coffee/ +.. _Common Lisp: https://pypi.org/project/sphinxcontrib-cldomain/ +.. _dqn: https://pypi.org/project/sphinxcontrib-dqndomain/ +.. _Erlang: https://pypi.org/project/sphinxcontrib-erlangdomain/ +.. _Go: https://pypi.org/project/sphinxcontrib-golangdomain/ +.. _HTTP: https://pypi.org/project/sphinxcontrib-httpdomain/ +.. _Jinja: https://pypi.org/project/sphinxcontrib-jinjadomain/ +.. _Lasso: https://pypi.org/project/sphinxcontrib-lassodomain/ +.. _MATLAB: https://pypi.org/project/sphinxcontrib-matlabdomain/ +.. _Operation: https://pypi.org/project/sphinxcontrib-operationdomain/ +.. _PHP: https://pypi.org/project/sphinxcontrib-phpdomain/ +.. _Ruby: https://github.com/sphinx-contrib/rubydomain +.. _Scala: https://pypi.org/project/sphinxcontrib-scaladomain/ diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst new file mode 100644 index 0000000..5fc897d --- /dev/null +++ b/doc/usage/restructuredtext/field-lists.rst @@ -0,0 +1,78 @@ +.. highlight:: rst + +=========== +Field Lists +=========== + +:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of +fields marked up like this:: + + :fieldname: Field content + +Sphinx extends standard docutils behavior for field lists and adds some extra +functionality that is covered in this section. + +.. note:: + + The values of field lists will be parsed as + strings. You cannot use Python collections such as lists or dictionaries. + + +.. _metadata: + +File-wide metadata +------------------ + +A field list near the top of a file is normally parsed by docutils as the +*docinfo* and shown on the page. However, in Sphinx, a field list preceding +any other markup is moved from the *docinfo* to the Sphinx environment as +document metadata, and is not displayed in the output. + +.. note:: + + A field list appearing after the document title *will* be part of the + *docinfo* as normal and will be displayed in the output. + + +Special metadata fields +----------------------- + +Sphinx provides custom behavior for bibliographic fields compared to docutils. + +At the moment, these metadata fields are recognized: + +``tocdepth`` + The maximum depth for a table of contents of this file. :: + + :tocdepth: 2 + + .. note:: + + This metadata effects to the depth of local toctree. But it does not + effect to the depth of *global* toctree. So this would not be change + the sidebar of some themes which uses global one. + + .. versionadded:: 0.4 + +``nocomments`` + If set, the web application won't display a comment form for a page + generated from this source file. :: + + :nocomments: + +``orphan`` + If set, warnings about this file not being included in any toctree will be + suppressed. :: + + :orphan: + + .. versionadded:: 1.0 + +``nosearch`` + If set, full text search for this file is disabled. :: + + :nosearch: + + .. note:: object search is still available even if `nosearch` option is set. + + .. versionadded:: 3.0 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst new file mode 100644 index 0000000..87b6ed6 --- /dev/null +++ b/doc/usage/restructuredtext/index.rst @@ -0,0 +1,24 @@ +.. _rst-index: + +================ +reStructuredText +================ + +reStructuredText (reST) is the default plaintext markup language used by both +Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while +Sphinx extends this to support additional functionality. + +The below guides go through the most important aspects of reST. For the +authoritative reStructuredText reference, refer to the `docutils +documentation`__. + +__ https://docutils.sourceforge.io/rst.html + +.. toctree:: + :maxdepth: 2 + + basics + roles + directives + field-lists + domains diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst new file mode 100644 index 0000000..e468de9 --- /dev/null +++ b/doc/usage/restructuredtext/roles.rst @@ -0,0 +1,536 @@ +.. highlight:: rst + +===== +Roles +===== + +Sphinx uses interpreted text roles to insert semantic markup into documents. +They are written as ``:rolename:`content```. + +.. note:: + + The default role (```content```) has no special meaning by default. You are + free to use it for anything you like, e.g. variable names; use the + :confval:`default_role` config value to set it to a known role -- the + :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find + Python objects are very useful for this. + +See :doc:`/usage/restructuredtext/domains` for roles added by domains. + + +.. _xref-syntax: + +Cross-referencing syntax +------------------------ + +Cross-references are generated by many semantic interpreted text roles. +Basically, you only need to write ``:role:`target```, and a link will be +created to the item named *target* of the type indicated by *role*. The link's +text will be the same as *target*. + +There are some additional facilities, however, that make cross-referencing +roles more versatile: + +* You may supply an explicit title and reference target, like in reST direct + hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link + text will be *title*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* If you prefix the content with ``~``, the link text will only be the last + component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This + does not work with all cross-reference roles, but is domain specific. + + In HTML output, the link's ``title`` attribute (that is e.g. shown as a + tool-tip on mouse-hover) will always be the full target name. + + +.. _any-role: + +Cross-referencing anything +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. rst:role:: any + + .. versionadded:: 1.3 + + This convenience role tries to do its best to find a valid target for its + reference text. + + * First, it tries standard cross-reference targets that would be referenced + by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. + + Custom objects added to the standard domain by extensions (see + :meth:`.Sphinx.add_object_type`) are also searched. + + * Then, it looks for objects (targets) in all loaded domains. It is up to + the domains how specific a match must be. For example, in the Python + domain a reference of ``:any:`Builder``` would match the + ``sphinx.builders.Builder`` class. + + If none or multiple targets are found, a warning will be emitted. In the + case of multiple targets, you can change "any" to a specific role. + + This role is a good candidate for setting :confval:`default_role`. If you + do, you can write cross-references without a lot of markup overhead. For + example, in this Python function documentation:: + + .. function:: install() + + This function installs a `handler` for every signal known by the + `signal` module. See the section `about-signals` for more information. + + there could be references to a glossary term (usually ``:term:`handler```), a + Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a + section (usually ``:ref:`about-signals```). + + The :rst:role:`any` role also works together with the + :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is + found, all object types of intersphinx inventories are also searched. + +Cross-referencing objects +^^^^^^^^^^^^^^^^^^^^^^^^^ + +These roles are described with their respective domains: + +* :ref:`Python <python-roles>` +* :ref:`C <c-roles>` +* :ref:`C++ <cpp-roles>` +* :ref:`JavaScript <js-roles>` +* :ref:`ReST <rst-roles>` + + +.. _ref-role: + +Cross-referencing arbitrary locations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. rst:role:: ref + + To support cross-referencing to arbitrary locations in any document, the + standard reST labels are used. For this to work label names must be unique + throughout the entire documentation. There are two ways in which you can + refer to labels: + + * If you place a label directly before a section title, you can reference to + it with ``:ref:`label-name```. For example:: + + .. _my-reference-label: + + Section to cross-reference + -------------------------- + + This is the text of the section. + + It refers to the section itself, see :ref:`my-reference-label`. + + The ``:ref:`` role would then generate a link to the section, with the + link title being "Section to cross-reference". This works just as well + when section and reference are in different source files. + + Automatic labels also work with figures. For example:: + + .. _my-figure: + + .. figure:: whatever + + Figure caption + + In this case, a reference ``:ref:`my-figure``` would insert a reference + to the figure with link text "Figure caption". + + The same works for tables that are given an explicit caption using the + :dudir:`table` directive. + + * Labels that aren't placed before a section title can still be referenced, + but you must give the link an explicit title, using this syntax: + ``:ref:`Link title <label-name>```. + + .. note:: + + Reference labels must start with an underscore. When referencing a label, + the underscore must be omitted (see examples above). + + Using :rst:role:`ref` is advised over standard reStructuredText links to + sections (like ```Section title`_``) because it works across files, when + section headings are changed, will raise warnings if incorrect, and works + for all builders that support cross-references. + + +Cross-referencing documents +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 0.6 + +There is also a way to directly link to documents: + +.. rst:role:: doc + + Link to the specified document; the document name can be specified in + absolute or relative fashion. For example, if the reference + ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link + refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or + ``:doc:`../people```, the link refers to ``people``. + + If no explicit link text is given (like usual: ``:doc:`Monty Python members + </people>```), the link caption will be the title of the given document. + + +Referencing downloadable files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 0.6 + +.. rst:role:: download + + This role lets you link to files within your source tree that are not reST + documents that can be viewed, but files that can be downloaded. + + When you use this role, the referenced file is automatically marked for + inclusion in the output when building (obviously, for HTML output only). + All downloadable files are put into a ``_downloads/<unique hash>/`` + subdirectory of the output directory; duplicate filenames are handled. + + An example:: + + See :download:`this example script <../example.py>`. + + The given filename is usually relative to the directory the current source + file is contained in, but if it absolute (starting with ``/``), it is taken + as relative to the top source directory. + + The ``example.py`` file will be copied to the output directory, and a + suitable link generated to it. + + Not to show unavailable download links, you should wrap whole paragraphs that + have this role:: + + .. only:: builder_html + + See :download:`this example script <../example.py>`. + +Cross-referencing figures by figure number +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 1.3 + +.. versionchanged:: 1.5 + `numref` role can also refer sections. + And `numref` allows `{name}` for the link text. + +.. rst:role:: numref + + Link to the specified figures, tables, code-blocks and sections; the standard + reST labels are used. When you use this role, it will insert a reference to + the figure with link text by its figure number like "Fig. 1.1". + + If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig. + %s) <my-figure>```), the link caption will serve as title of the reference. + As placeholders, `%s` and `{number}` get replaced by the figure + number and `{name}` by the figure caption. + If no explicit link text is given, the :confval:`numfig_format` setting is + used as fall-back default. + + If :confval:`numfig` is ``False``, figures are not numbered, + so this role inserts not a reference but the label or the link text. + +Cross-referencing other items of interest +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following roles do possibly create a cross-reference, but do not refer to +objects: + +.. rst:role:: envvar + + An environment variable. Index entries are generated. Also generates a link + to the matching :rst:dir:`envvar` directive, if it exists. + +.. rst:role:: token + + The name of a grammar token (used to create links between + :rst:dir:`productionlist` directives). + +.. rst:role:: keyword + + The name of a keyword in Python. This creates a link to a reference label + with that name, if it exists. + +.. rst:role:: option + + A command-line option to an executable program. This generates a link to + a :rst:dir:`option` directive, if it exists. + + +The following role creates a cross-reference to a term in a +:ref:`glossary <glossary-directive>`: + +.. rst:role:: term + + Reference to a term in a glossary. A glossary is created using the + ``glossary`` directive containing a definition list with terms and + definitions. It does not have to be in the same file as the ``term`` markup, + for example the Python docs have one global glossary in the ``glossary.rst`` + file. + + If you use a term that's not explained in a glossary, you'll get a warning + during build. + +Inline code highlighting +------------------------ + +.. rst:role:: code + + An *inline* code example. When used directly, this role just displays the + text *without* syntax highlighting, as a literal. + + .. code-block:: rst + + By default, inline code such as :code:`1 + 2` just displays without + highlighting. + + Displays: By default, inline code such as :code:`1 + 2` just displays without + highlighting. + + Unlike the :rst:dir:`code-block` directive, this role does not respect the + default language set by the :rst:dir:`highlight` directive. + + To enable syntax highlighting, you must first use the Docutils :dudir:`role` + directive to define a custom role associated with a specific language: + + .. code-block:: rst + + .. role:: python(code) + :language: python + + In Python, :python:`1 + 2` is equal to :python:`3`. + + To display a multi-line code example, use the :rst:dir:`code-block` directive + instead. + +Math +---- + +.. rst:role:: math + + Role for inline math. Use like this:: + + Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`. + + Displays: Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`. + +.. rst:role:: eq + + Same as :rst:role:`math:numref`. + + +Other semantic markup +--------------------- + +The following roles don't do anything special except formatting the text in a +different style: + +.. rst:role:: abbr + + An abbreviation. If the role content contains a parenthesized explanation, + it will be treated specially: it will be shown in a tool-tip in HTML, and + output only once in LaTeX. + + For example: ``:abbr:`LIFO (last-in, first-out)``` displays + :abbr:`LIFO (last-in, first-out)`. + + .. versionadded:: 0.6 + +.. rst:role:: command + + The name of an OS-level command, such as ``rm``. + + For example: :command:`rm` + +.. rst:role:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + + For example: :dfn:`binary mode` + +.. rst:role:: file + + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ... + + Displays: ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. + +.. rst:role:: guilabel + + Labels presented as part of an interactive user interface should be marked + using ``guilabel``. This includes labels from text-based interfaces such as + those created using :mod:`curses` or other text-based libraries. Any label + used in the interface should be marked with this role, including button + labels, window titles, field names, menu and menu selection names, and even + values in selection lists. + + .. versionchanged:: 1.0 + An accelerator key for the GUI label can be included using an ampersand; + this will be stripped and displayed underlined in the output (for example: + ``:guilabel:`&Cancel``` displays :guilabel:`&Cancel`). To include a literal + ampersand, double it. + +.. rst:role:: kbd + + Mark a sequence of keystrokes. What form the key sequence takes may depend + on platform- or application-specific conventions. When there are no + relevant conventions, the names of modifier keys should be spelled out, to + improve accessibility for new users and non-native speakers. For example, + an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without + reference to a specific application or platform, the same sequence should be + marked as ``:kbd:`Control-x Control-f```, displaying :kbd:`C-x C-f` and + :kbd:`Control-x Control-f` respectively. + +.. rst:role:: mailheader + + The name of an RFC 822-style mail header. This markup does not imply that + the header is being used in an email message, but can be used to refer to + any header of the same "style." This is also used for headers defined by + the various MIME specifications. The header name should be entered in the + same way it would normally be found in practice, with the camel-casing + conventions being preferred where there is more than one common usage. For + example: ``:mailheader:`Content-Type``` displays :mailheader:`Content-Type`. + +.. rst:role:: makevar + + The name of a :command:`make` variable. + + For example: :makevar:`help` + +.. rst:role:: manpage + + A reference to a Unix manual page including the section, e.g. + ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an + external site rendering the manpage if :confval:`manpages_url` is defined. + +.. rst:role:: menuselection + + Menu selections should be marked using the ``menuselection`` role. This is + used to mark a complete sequence of menu selections, including selecting + submenus and choosing a specific operation, or any subsequence of such a + sequence. The names of individual selections should be separated by + ``-->``. + + For example, to mark the selection "Start > Programs", use this markup:: + + :menuselection:`Start --> Programs` + + Displays: :menuselection:`Start --> Programs` + + When including a selection that includes some trailing indicator, such as + the ellipsis some operating systems use to indicate that the command opens a + dialog, the indicator should be omitted from the selection name. + + ``menuselection`` also supports ampersand accelerators just like + :rst:role:`guilabel`. + +.. rst:role:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + + For example: :mimetype:`text/plain` + +.. rst:role:: newsgroup + + The name of a Usenet newsgroup. + + For example: :newsgroup:`comp.lang.python` + +.. todo:: Is this not part of the standard domain? + +.. rst:role:: program + + The name of an executable program. This may differ from the file name for + the executable for some platforms. In particular, the ``.exe`` (or other) + extension should be omitted for Windows programs. + + For example: :program:`curl` + +.. rst:role:: regexp + + A regular expression. Quotes should not be included. + + For example: :regexp:`([abc])+` + +.. rst:role:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in :rst:role:`file`. For + example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be + emphasized: :samp:`print 1+{variable}` + + If you don't need the "variable part" indication, use the standard + :rst:role:`code` role instead. + + .. versionchanged:: 1.8 + Allowed to escape curly braces with backslash + +There is also an :rst:role:`index` role to generate index entries. + +The following roles generate external links: + +.. rst:role:: pep + + A reference to a Python Enhancement Proposal. This generates appropriate + index entries. The text "PEP *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified PEP. You can + link to a specific section by saying ``:pep:`number#anchor```. + + For example: :pep:`8` + +.. rst:role:: rfc + + A reference to an Internet Request for Comments. This generates appropriate + index entries. The text "RFC *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified RFC. You can + link to a specific section by saying ``:rfc:`number#anchor```. + + For example: :rfc:`2324` + +Note that there are no special roles for including hyperlinks as you can use +the standard reST markup for that purpose. + + +.. _default-substitutions: + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by +default. They are set in the build configuration file. + +.. describe:: |release| + + Replaced by the project release the documentation refers to. This is meant + to be the full version string including alpha/beta/release candidate tags, + e.g. ``2.5.2b3``. Set by :confval:`release`. + +.. describe:: |version| + + Replaced by the project version the documentation refers to. This is meant to + consist only of the major and minor version parts, e.g. ``2.5``, even for + version 2.5.1. Set by :confval:`version`. + +.. describe:: |today| + + Replaced by either today's date (the date on which the document is read), or + the date set in the build configuration file. Normally has the format + ``April 14, 2007``. Set by :confval:`today_fmt` and :confval:`today`. + +.. describe:: |translation progress| + + Replaced by the translation progress of the document. + This substitution is intented for use by document translators + as a marker for the translation progress of the document. diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst new file mode 100644 index 0000000..c33c7d4 --- /dev/null +++ b/doc/usage/theming.rst @@ -0,0 +1,364 @@ +.. highlight:: python + +.. _html-themes: + +HTML Theming +============ + +Sphinx provides a number of builders for HTML and HTML-based formats. + +Builders +-------- + +.. todo:: Populate when the 'builders' document is split up. + + +Themes +------ + +.. versionadded:: 0.6 + +.. note:: + + This section provides information about using pre-existing HTML themes. If + you wish to create your own theme, refer to + :doc:`/development/theming`. + +Sphinx supports changing the appearance of its HTML output via *themes*. A +theme is a collection of HTML templates, stylesheet(s) and other static files. +Additionally, it has a configuration file which specifies from which theme to +inherit, which highlighting style to use, and what options exist for customizing +the theme's look and feel. + +Themes are meant to be project-unaware, so they can be used for different +projects without change. + +Using a theme +~~~~~~~~~~~~~ + +Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these +do not need to be installed, you only need to set the :confval:`html_theme` +config value. For example, to enable the ``classic`` theme, add the following +to :file:`conf.py`:: + + html_theme = "classic" + +You can also set theme-specific options using the :confval:`html_theme_options` +config value. These options are generally used to change the look and feel of +the theme. For example, to place the sidebar on the right side and a black +background for the relation bar (the bar with the navigation links at the +page's top and bottom), add the following :file:`conf.py`:: + + html_theme_options = { + "rightsidebar": "true", + "relbarbgcolor": "black" + } + +If the theme does not come with Sphinx, it can be in two static forms or as a +Python package. For the static forms, either a directory (containing +:file:`theme.conf` and other needed files), or a zip file with the same +contents is supported. The directory or zipfile must be put where Sphinx can +find it; for this there is the config value :confval:`html_theme_path`. This +can be a list of directories, relative to the directory containing +:file:`conf.py`, that can contain theme directories or zip files. For example, +if you have a theme in the file :file:`blue.zip`, you can put it right in the +directory containing :file:`conf.py` and use this configuration:: + + html_theme = "blue" + html_theme_path = ["."] + +The third form is a Python package. If a theme you want to use is distributed +as a Python package, you can use it after installing + +.. code-block:: console + + # installing theme package + $ pip install sphinxjp.themes.dotted + +Once installed, this can be used in the same manner as a directory or +zipfile-based theme:: + + html_theme = "dotted" + +For more information on the design of themes, including information about +writing your own themes, refer to :doc:`/development/theming`. + +.. _builtin-themes: + +Builtin themes +~~~~~~~~~~~~~~ + +.. cssclass:: longtable, standard + ++--------------------+--------------------+ +| **Theme overview** | | ++--------------------+--------------------+ +| |alabaster| | |classic| | +| | | +| *alabaster* | *classic* | ++--------------------+--------------------+ +| |sphinxdoc| | |scrolls| | +| | | +| *sphinxdoc* | *scrolls* | ++--------------------+--------------------+ +| |agogo| | |traditional| | +| | | +| *agogo* | *traditional* | ++--------------------+--------------------+ +| |nature| | |haiku| | +| | | +| *nature* | *haiku* | ++--------------------+--------------------+ +| |pyramid| | |bizstyle| | +| | | +| *pyramid* | *bizstyle* | ++--------------------+--------------------+ + +.. |alabaster| image:: /_static/themes/alabaster.png +.. |classic| image:: /_static/themes/classic.png +.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png +.. |scrolls| image:: /_static/themes/scrolls.png +.. |agogo| image:: /_static/themes/agogo.png +.. |traditional| image:: /_static/themes/traditional.png +.. |nature| image:: /_static/themes/nature.png +.. |haiku| image:: /_static/themes/haiku.png +.. |pyramid| image:: /_static/themes/pyramid.png +.. |bizstyle| image:: /_static/themes/bizstyle.png + +Sphinx comes with a selection of themes to choose from. + +Note that from these themes only the Alabaster and Scrolls themes are +mobile-optimated, the other themes resort to horizontal scrolling +if the screen is too narrow. + +.. cssclass:: clear + +These themes are: + +**basic** + This is a basically unstyled layout used as the base for the + other themes, and usable as the base for custom themes as well. The HTML + contains all important elements like sidebar and relation bar. There are + these options (which are inherited by the other themes): + + - **nosidebar** (true or false): Don't include the sidebar. Defaults to + ``False``. + + - **sidebarwidth** (int or str): Width of the sidebar in pixels. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Defaults to 230 pixels. + + - **body_min_width** (int or str): Minimal width of the document body. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Use 0 if you don't want + a width limit. Defaults may depend on the theme (often 450px). + + - **body_max_width** (int or str): Maximal width of the document body. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Use 'none' if you don't + want a width limit. Defaults may depend on the theme (often 800px). + + - **navigation_with_keys** (true or false): Allow navigating + with the following keyboard shortcuts: + + - :kbd:`Left arrow`: previous page + - :kbd:`Right arrow`: next page + + Defaults to ``False``. + + - **enable_search_shortcuts** (true or false): Allow jumping to the search box + with :kbd:`/` and allow removal of search highlighting with :kbd:`Esc`. + + Defaults to ``True``. + + - **globaltoc_collapse** (true or false): Only expand subsections + of the current document in ``globaltoc.html`` + (see :confval:`html_sidebars`). + Defaults to ``True``. + + .. versionadded:: 3.1 + + - **globaltoc_includehidden** (true or false): Show even those + subsections in ``globaltoc.html`` (see :confval:`html_sidebars`) + which have been included with the ``:hidden:`` flag of the + :rst:dir:`toctree` directive. + Defaults to ``False``. + + .. versionadded:: 3.1 + + - **globaltoc_maxdepth** (int): The maximum depth of the toctree in + ``globaltoc.html`` (see :confval:`html_sidebars`). Set it to -1 to allow + unlimited depth. Defaults to the max depth selected in the toctree directive. + + .. versionadded:: 3.2 + +**alabaster** + `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz + (especially as used in his Requests project), which was itself originally + based on @mitsuhiko's theme used for Flask & related projects. Refer to its + `installation page`_ for information on how to configure + :confval:`html_sidebars` for its use. + + .. _Alabaster theme: https://pypi.org/project/alabaster/ + .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html + +**classic** + This is the classic theme, which looks like `the Python 2 + documentation <https://docs.python.org/2/>`_. It can be customized via + these options: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``False``. + + - **stickysidebar** (true or false): Make the sidebar "fixed" so that it + doesn't scroll out of view for long body content. This may not work well + with all browsers. Defaults to ``False``. + + - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript + snippet that makes the sidebar collapsible via a button on its side. + Defaults to ``False``. + + - **externalrefs** (true or false): Display external links differently from + internal links. Defaults to ``False``. + + There are also various color and font options that can change the color scheme + without having to write a custom stylesheet: + + - **footerbgcolor** (CSS color): Background color for the footer line. + - **footertextcolor** (CSS color): Text color for the footer line. + - **sidebarbgcolor** (CSS color): Background color for the sidebar. + - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse + button (used when *collapsiblesidebar* is ``True``). + - **sidebartextcolor** (CSS color): Text color for the sidebar. + - **sidebarlinkcolor** (CSS color): Link color for the sidebar. + - **relbarbgcolor** (CSS color): Background color for the relation bar. + - **relbartextcolor** (CSS color): Text color for the relation bar. + - **relbarlinkcolor** (CSS color): Link color for the relation bar. + - **bgcolor** (CSS color): Body background color. + - **textcolor** (CSS color): Body text color. + - **linkcolor** (CSS color): Body link color. + - **visitedlinkcolor** (CSS color): Body color for visited links. + - **headbgcolor** (CSS color): Background color for headings. + - **headtextcolor** (CSS color): Text color for headings. + - **headlinkcolor** (CSS color): Link color for headings. + - **codebgcolor** (CSS color): Background color for code blocks. + - **codetextcolor** (CSS color): Default text color for code blocks, if not + set differently by the highlighting style. + + - **bodyfont** (CSS font-family): Font for normal text. + - **headfont** (CSS font-family): Font for headings. + +**sphinxdoc** + The theme originally used by this documentation. It features + a sidebar on the right side. There are currently no options beyond + *nosidebar* and *sidebarwidth*. + + .. note:: + + The Sphinx documentation now uses + `an adjusted version of the sphinxdoc theme + <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_. + +**scrolls** + A more lightweight theme, based on `the Jinja documentation + <https://jinja.palletsprojects.com/>`_. The following color options are + available: + + - **headerbordercolor** + - **subheadlinecolor** + - **linkcolor** + - **visitedlinkcolor** + - **admonitioncolor** + +**agogo** + A theme created by Andi Albrecht. The following options are supported: + + - **bodyfont** (CSS font family): Font for normal text. + - **headerfont** (CSS font family): Font for headings. + - **pagewidth** (CSS length): Width of the page content, default 70em. + - **documentwidth** (CSS length): Width of the document (without sidebar), + default 50em. + - **sidebarwidth** (CSS length): Width of the sidebar, default 20em. + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``True``. + - **bgcolor** (CSS color): Background color. + - **headerbg** (CSS value for "background"): background for the header area, + default a grayish gradient. + - **footerbg** (CSS value for "background"): background for the footer area, + default a light gray gradient. + - **linkcolor** (CSS color): Body link color. + - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2> + headings. + - **headerlinkcolor** (CSS color): Color for the backreference link in + headings. + - **textalign** (CSS *text-align* value): Text alignment for the body, default + is ``justify``. + +**nature** + A greenish theme. There are currently no options beyond + *nosidebar* and *sidebarwidth*. + +**pyramid** + A theme from the Pyramid web framework project, designed by Blaise Laflamme. + There are currently no options beyond *nosidebar* and *sidebarwidth*. + +**haiku** + A theme without sidebar inspired by the `Haiku OS user guide + <https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following + options are supported: + + - **full_logo** (true or false, default ``False``): If this is true, the + header will only show the :confval:`html_logo`. Use this for large logos. + If this is false, the logo (if present) will be shown floating right, and + the documentation title will be put in the header. + + - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**, + **hoverlinkcolor** (CSS colors): Colors for various body elements. + +**traditional** + A theme resembling the old Python documentation. There are + currently no options beyond *nosidebar* and *sidebarwidth*. + +**epub** + A theme for the epub builder. This theme tries to save visual + space which is a sparse resource on ebook readers. The following options + are supported: + + - **relbar1** (true or false, default ``True``): If this is true, the + `relbar1` block is inserted in the epub output, otherwise it is omitted. + + - **footer** (true or false, default ``True``): If this is true, the + `footer` block is inserted in the epub output, otherwise it is omitted. + +**bizstyle** + A simple bluish theme. The following options are supported + beyond *nosidebar* and *sidebarwidth*: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``False``. + +.. versionadded:: 1.3 + 'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme. + +.. versionchanged:: 1.3 + The 'default' theme has been renamed to 'classic'. 'default' is still + available, however it will emit a notice that it is an alias for the new + 'alabaster' theme. + +.. _third-party-themes: + +Third Party Themes +~~~~~~~~~~~~~~~~~~ + +There are many third-party themes created 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 +.. __: https://gitlab.com/explore?name=sphinx+theme |