diff options
Diffstat (limited to 'doc/usage/extensions')
23 files changed, 4496 insertions, 0 deletions
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. |