diff options
Diffstat (limited to 'doc/extdev')
| -rw-r--r-- | doc/extdev/appapi.rst | 456 | ||||
| -rw-r--r-- | doc/extdev/builderapi.rst | 46 | ||||
| -rw-r--r-- | doc/extdev/collectorapi.rst | 9 | ||||
| -rw-r--r-- | doc/extdev/deprecated.rst | 1811 | ||||
| -rw-r--r-- | doc/extdev/domainapi.rst | 32 | ||||
| -rw-r--r-- | doc/extdev/envapi.rst | 58 | ||||
| -rw-r--r-- | doc/extdev/i18n.rst | 97 | ||||
| -rw-r--r-- | doc/extdev/index.rst | 218 | ||||
| -rw-r--r-- | doc/extdev/logging.rst | 66 | ||||
| -rw-r--r-- | doc/extdev/markupapi.rst | 152 | ||||
| -rw-r--r-- | doc/extdev/nodes.rst | 71 | ||||
| -rw-r--r-- | doc/extdev/parserapi.rst | 38 | ||||
| -rw-r--r-- | doc/extdev/projectapi.rst | 9 | ||||
| -rw-r--r-- | doc/extdev/utils.rst | 37 |
14 files changed, 3100 insertions, 0 deletions
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst new file mode 100644 index 0000000..fc92a77 --- /dev/null +++ b/doc/extdev/appapi.rst @@ -0,0 +1,456 @@ +.. highlight:: rest + +Application API +=============== + +.. module:: sphinx.application + :synopsis: Application class and extensibility interface. + + +Each Sphinx extension is a Python module with at least a :func:`setup` +function. This function is called at initialization time with one argument, +the application object representing the Sphinx process. + +.. class:: Sphinx + + This application object has the public API described in the following. + +Extension setup +--------------- + +These methods are usually called in an extension's ``setup()`` function. + +Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext` +package. + +.. currentmodule:: sphinx.application + +.. automethod:: Sphinx.setup_extension + +.. automethod:: Sphinx.require_sphinx + +.. automethod:: Sphinx.connect + +.. automethod:: Sphinx.disconnect + +.. automethod:: Sphinx.add_builder + +.. automethod:: Sphinx.add_config_value + +.. automethod:: Sphinx.add_event + +.. automethod:: Sphinx.set_translator + +.. automethod:: Sphinx.add_node + +.. automethod:: Sphinx.add_enumerable_node + +.. automethod:: Sphinx.add_directive + +.. automethod:: Sphinx.add_role + +.. automethod:: Sphinx.add_generic_role + +.. automethod:: Sphinx.add_domain + +.. automethod:: Sphinx.add_directive_to_domain + +.. automethod:: Sphinx.add_role_to_domain + +.. automethod:: Sphinx.add_index_to_domain + +.. automethod:: Sphinx.add_object_type + +.. automethod:: Sphinx.add_crossref_type + +.. automethod:: Sphinx.add_transform + +.. automethod:: Sphinx.add_post_transform + +.. automethod:: Sphinx.add_js_file + +.. automethod:: Sphinx.add_css_file + +.. automethod:: Sphinx.add_latex_package + +.. automethod:: Sphinx.add_lexer + +.. automethod:: Sphinx.add_autodocumenter + +.. automethod:: Sphinx.add_autodoc_attrgetter + +.. automethod:: Sphinx.add_search_language + +.. automethod:: Sphinx.add_source_suffix + +.. automethod:: Sphinx.add_source_parser + +.. automethod:: Sphinx.add_env_collector + +.. automethod:: Sphinx.add_html_theme + +.. automethod:: Sphinx.add_html_math_renderer + +.. automethod:: Sphinx.add_message_catalog + +.. automethod:: Sphinx.is_parallel_allowed + +.. exception:: ExtensionError + + All these methods raise this exception if something went wrong with the + extension API. + + +Emitting events +--------------- + +.. class:: Sphinx + :noindex: + + .. automethod:: emit + + .. automethod:: emit_firstresult + + +Sphinx runtime information +-------------------------- + +The application object also provides runtime information as attributes. + +.. attribute:: Sphinx.project + + Target project. See :class:`.Project`. + +.. attribute:: Sphinx.srcdir + + Source directory. + +.. attribute:: Sphinx.confdir + + Directory containing ``conf.py``. + +.. attribute:: Sphinx.doctreedir + + Directory for storing pickled doctrees. + +.. attribute:: Sphinx.outdir + + Directory for storing built document. + + +.. _events: + +Sphinx core events +------------------ + +These events are known to the core. The arguments shown are given to the +registered event handlers. Use :meth:`.Sphinx.connect` in an extension's +``setup`` function (note that ``conf.py`` can also have a ``setup`` function) to +connect handlers to the events. Example: + +.. code-block:: python + + def source_read_handler(app, docname, source): + print('do something here...') + + def setup(app): + app.connect('source-read', source_read_handler) + + +Below is an overview of each event that happens during a build. In the list +below, we include the event name, its callback parameters, and the input and output +type for that event: + +.. code-block:: none + + 1. event.config-inited(app,config) + 2. event.builder-inited(app) + 3. event.env-get-outdated(app, env, added, changed, removed) + 4. event.env-before-read-docs(app, env, docnames) + + for docname in docnames: + 5. event.env-purge-doc(app, env, docname) + + if doc changed and not removed: + 6. source-read(app, docname, source) + 7. run source parsers: text -> docutils.document + - parsers can be added with the app.add_source_parser() API + 8. apply transforms based on priority: docutils.document -> docutils.document + - event.doctree-read(app, doctree) is called in the middle of transforms, + transforms come before/after this event depending on their priority. + + 9. event.env-merge-info(app, env, docnames, other) + - if running in parallel mode, this event will be emitted for each process + + 10. event.env-updated(app, env) + 11. event.env-get-updated(app, env) + 12. event.env-check-consistency(app, env) + + # The updated-docs list can be builder dependent, but generally includes all new/changed documents, + # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree + # For builders that output a single page, they are first joined into a single doctree before post-transforms + # or the doctree-resolved event is emitted + for docname in updated-docs: + 13. apply post-transforms (by priority): docutils.document -> docutils.document + 14. event.doctree-resolved(app, doctree, docname) + - In the event that any reference nodes fail to resolve, the following may emit: + - event.missing-reference(env, node, contnode) + - event.warn-missing-reference(domain, node) + + 15. Generate output files + 16. event.build-finished(app, exception) + +Here is a more detailed list of these events. + +.. event:: builder-inited (app) + + Emitted when the builder object has been created. It is available as + ``app.builder``. + +.. event:: config-inited (app, config) + + Emitted when the config object has been initialized. + + .. versionadded:: 1.8 + +.. event:: env-get-outdated (app, env, added, changed, removed) + + Emitted when the environment determines which source files have changed and + should be re-read. *added*, *changed* and *removed* are sets of docnames + that the environment has determined. You can return a list of docnames to + re-read in addition to these. + + .. versionadded:: 1.1 + +.. event:: env-purge-doc (app, env, docname) + + Emitted when all traces of a source file should be cleaned from the + environment, that is, if the source file is removed or before it is freshly + read. This is for extensions that keep their own caches in attributes of the + environment. + + For example, there is a cache of all modules on the environment. When a + source file has been changed, the cache's entries for the file are cleared, + since the module declarations could have been removed from the file. + + .. versionadded:: 0.5 + +.. event:: env-before-read-docs (app, env, docnames) + + Emitted after the environment has determined the list of all added and + changed files and just before it reads them. It allows extension authors to + reorder the list of docnames (*inplace*) before processing, or add more + docnames that Sphinx did not consider changed (but never add any docnames + that are not in ``env.found_docs``). + + You can also remove document names; do this with caution since it will make + Sphinx treat changed files as unchanged. + + .. versionadded:: 1.3 + +.. event:: source-read (app, docname, source) + + Emitted when a source file has been read. The *source* argument is a list + whose single element is the contents of the source file. You can process the + contents and replace this item to implement source-level transformations. + + For example, if you want to use ``$`` signs to delimit inline math, like in + LaTeX, you can use a regular expression to replace ``$...$`` by + ``:math:`...```. + + .. versionadded:: 0.5 + +.. event:: object-description-transform (app, domain, objtype, contentnode) + + Emitted when an object description directive has run. The *domain* and + *objtype* arguments are strings indicating object description of the object. + And *contentnode* is a content for the object. It can be modified in-place. + + .. versionadded:: 2.4 + +.. event:: doctree-read (app, doctree) + + Emitted when a doctree has been parsed and read by the environment, and is + about to be pickled. The *doctree* can be modified in-place. + +.. event:: missing-reference (app, env, node, contnode) + + Emitted when a cross-reference to an object cannot be resolved. + If the event handler can resolve the reference, it should return a + new docutils node to be inserted in the document tree in place of the node + *node*. Usually this node is a :class:`reference` node containing *contnode* + as a child. + If the handler can not resolve the cross-reference, + it can either return ``None`` to let other handlers try, + or raise :class:`NoUri` to prevent other handlers in trying and suppress + a warning about this cross-reference being unresolved. + + :param env: The build environment (``app.builder.env``). + :param node: The :class:`pending_xref` node to be resolved. Its attributes + ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes + determine the type and target of the reference. + :param contnode: The node that carries the text and formatting inside the + future reference and should be a child of the returned reference node. + + .. versionadded:: 0.5 + +.. event:: warn-missing-reference (app, domain, node) + + Emitted when a cross-reference to an object cannot be resolved even after + :event:`missing-reference`. If the event handler can emit warnings for + the missing reference, it should return ``True``. The configuration variables + :confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex` prevent the + event from being emitted for the corresponding nodes. + + .. versionadded:: 3.4 + +.. event:: doctree-resolved (app, doctree, docname) + + Emitted when a doctree has been "resolved" by the environment, that is, all + references have been resolved and TOCs have been inserted. The *doctree* can + be modified in place. + + Here is the place to replace custom nodes that don't have visitor methods in + the writers, so that they don't cause errors when the writers encounter them. + +.. event:: env-merge-info (app, env, docnames, other) + + This event is only emitted when parallel reading of documents is enabled. It + is emitted once for every subprocess that has read some documents. + + You must handle this event in an extension that stores data in the + environment in a custom location. Otherwise the environment in the main + process will not be aware of the information stored in the subprocess. + + *other* is the environment object from the subprocess, *env* is the + environment from the main process. *docnames* is a set of document names + that have been read in the subprocess. + + .. versionadded:: 1.3 + +.. event:: env-updated (app, env) + + Emitted when the :meth:`update` method of the build environment has + completed, that is, the environment and all doctrees are now up-to-date. + + You can return an iterable of docnames from the handler. These documents + will then be considered updated, and will be (re-)written during the writing + phase. + + .. versionadded:: 0.5 + + .. versionchanged:: 1.3 + The handlers' return value is now used. + +.. event:: env-check-consistency (app, env) + + Emitted when Consistency checks phase. You can check consistency of + metadata for whole of documents. + + .. versionadded:: 1.6 + + As a **experimental** event + +.. event:: html-collect-pages (app) + + Emitted when the HTML builder is starting to write non-document pages. You + can add pages to write by returning an iterable from this event consisting of + ``(pagename, context, templatename)``. + + .. versionadded:: 1.0 + +.. event:: html-page-context (app, pagename, templatename, context, doctree) + + Emitted when the HTML builder has created a context dictionary to render a + template with -- this can be used to add custom elements to the context. + + The *pagename* argument is the canonical name of the page being rendered, + that is, without ``.html`` suffix and using slashes as path separators. The + *templatename* is the name of the template to render, this will be + ``'page.html'`` for all pages from reST documents. + + The *context* argument is a dictionary of values that are given to the + template engine to render the page and can be modified to include custom + values. Keys must be strings. + + The *doctree* argument will be a doctree when the page is created from a reST + documents; it will be ``None`` when the page is created from an HTML template + alone. + + You can return a string from the handler, it will then replace + ``'page.html'`` as the HTML template for this page. + + .. note:: You can install JS/CSS files for the specific page via + :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since + v3.5.0. + + .. versionadded:: 0.4 + + .. versionchanged:: 1.3 + The return value can now specify a template name. + +.. event:: linkcheck-process-uri (app, uri) + + Emitted when the linkcheck builder collects hyperlinks from document. *uri* + is a collected URI. The event handlers can modify the URI by returning a + string. + + .. versionadded:: 4.1 + +.. event:: build-finished (app, exception) + + Emitted when a build has finished, before Sphinx exits, usually used for + cleanup. This event is emitted even when the build process raised an + exception, given as the *exception* argument. The exception is reraised in + the application after the event handlers have run. If the build process + raised no exception, *exception* will be ``None``. This allows to customize + cleanup actions depending on the exception status. + + .. versionadded:: 0.5 + + +Checking the Sphinx version +--------------------------- + +.. currentmodule:: sphinx + +Use this to adapt your extension to API changes in Sphinx. + +.. autodata:: version_info + + +The Config object +----------------- + +.. currentmodule:: sphinx.config + +.. autoclass:: Config + + +.. _template-bridge: + +The template bridge +------------------- + +.. currentmodule:: sphinx.application + +.. autoclass:: TemplateBridge + :members: + + +.. _exceptions: + +Exceptions +---------- + +.. module:: sphinx.errors + +.. autoexception:: SphinxError + +.. autoexception:: ConfigError + +.. autoexception:: ExtensionError + +.. autoexception:: ThemeError + +.. autoexception:: VersionRequirementError diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst new file mode 100644 index 0000000..5c5a525 --- /dev/null +++ b/doc/extdev/builderapi.rst @@ -0,0 +1,46 @@ +.. _writing-builders: + +Builder API +=========== + +.. todo:: Expand this. + +.. currentmodule:: sphinx.builders + +.. class:: Builder + + This is the base class for all builders. + + These attributes should be set on builder classes: + + .. autoattribute:: name + .. autoattribute:: format + .. autoattribute:: epilog + .. autoattribute:: allow_parallel + .. autoattribute:: supported_image_types + .. autoattribute:: supported_remote_images + .. autoattribute:: supported_data_uri_images + .. autoattribute:: default_translator_class + + These methods are predefined and will be called from the application: + + .. automethod:: get_relative_uri + .. automethod:: build_all + .. automethod:: build_specific + .. automethod:: build_update + .. automethod:: build + + These methods can be overridden in concrete builder classes: + + .. automethod:: init + .. automethod:: get_outdated_docs + .. automethod:: get_target_uri + .. automethod:: prepare_writing + .. automethod:: write_doc + .. automethod:: finish + + **Attributes** + + .. attribute:: events + + An :class:`.EventManager` object. diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst new file mode 100644 index 0000000..cb4c30b --- /dev/null +++ b/doc/extdev/collectorapi.rst @@ -0,0 +1,9 @@ +.. _collector-api: + +Environment Collector API +------------------------- + +.. module:: sphinx.environment.collectors + +.. autoclass:: EnvironmentCollector + :members: diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst new file mode 100644 index 0000000..1692f2d --- /dev/null +++ b/doc/extdev/deprecated.rst @@ -0,0 +1,1811 @@ +.. _dev-deprecated-apis: + +Deprecated APIs +=============== + +On developing Sphinx, we are always careful to the compatibility of our APIs. +But, sometimes, the change of interface are needed for some reasons. In such +cases, we've marked them as deprecated. And they are kept during the two +major versions (for more details, please see :ref:`deprecation-policy`). + +The following is a list of deprecated interfaces. + +.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38} + +.. list-table:: deprecated APIs + :header-rows: 1 + :class: deprecated + :widths: 40, 10, 10, 40 + + * - Target + - Deprecated + - Removed + - Alternatives + + * - HTML 4 support + - 5.2 + - 7.0 + - N/A + + * - ``sphinx.util.path_stabilize`` + - 5.1 + - 7.0 + - ``sphinx.util.osutil.path_stabilize`` + + * - ``sphinx.util.get_matching_files`` + - 5.1 + - 7.0 + - ``sphinx.util.matching.get_matching_files`` + + * - ``sphinx.ext.napoleon.iterators`` + - 5.1 + - 7.0 + - ``pockets.iterators`` + + * - ``sphinx.util.stemmer`` + - 5.1 + - 7.0 + - ``snowballstemmer`` + + * - ``sphinx.util.jsdump`` + - 5.0 + - 7.0 + - The standard library ``json`` module. + + * - :doc:`Setuptools integration </usage/advanced/setuptools>` + - 5.0 + - 7.0 + - N/A + + * - The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()`` + - 5.0 + - 7.0 + - N/A + + * - The ``language`` argument of ``sphinx.util.i18n:format_date()`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.builders.html.html5_ready`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.io.read_doc()`` + - 5.0 + - 7.0 + - ``sphinx.builders.Builder.read_doc()`` + + * - ``sphinx.util.docutils.__version_info__`` + - 5.0 + - 7.0 + - ``docutils.__version_info__`` + + * - ``sphinx.util.docutils.is_html5_writer_available()`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXWriter.docclasses`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()`` + - 4.5 + - 6.0 + - N/A + + * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor`` + - 4.3 + - 6.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_indices`` + + * - ``sphinx.writers.html.HTMLTranslator._table_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html.HTMLTranslator._table_row_indices`` + + * - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_indices`` + + * - ``sphinx.writers.html5.HTML5Translator._table_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html5.HTML5Translator._table_row_indices`` + + * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment`` + - 4.1 + - 6.0 + - The required argument + + * - ``sphinx.application.Sphinx.html_theme`` + - 4.1 + - 6.0 + - ``sphinx.registry.SphinxComponentRegistry.html_themes`` + + * - ``sphinx.ext.autosummary._app`` + - 4.1 + - 6.0 + - N/A + + * - ``sphinx.util.docstrings.extract_metadata()`` + - 4.1 + - 6.0 + - ``sphinx.util.docstrings.separate_metadata()`` + + * - ``favicon`` variable in HTML templates + - 4.0 + - TBD + - ``favicon_url`` + + * - ``logo`` variable in HTML templates + - 4.0 + - TBD + - ``logo_url`` + + * - ``sphinx.directives.patches.ListTable`` + - 4.0 + - 6.0 + - ``docutils.parsers.rst.directives.tables.ListSVTable`` + + * - ``sphinx.directives.patches.RSTTable`` + - 4.0 + - 6.0 + - ``docutils.parsers.rst.directives.tables.RSTTable`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set`` + - 4.0 + - 6.0 + - ``sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.warn()`` + - 4.0 + - 6.0 + - :ref:`logging-api` + + * - ``sphinx.registry.SphinxComponentRegistry.get_source_input()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.registry.SphinxComponentRegistry.source_inputs`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.transforms.FigureAligner`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.pycompat.convert_with_2to3()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.pycompat.execfile_()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.smartypants`` + - 4.0 + - 6.0 + - ``docutils.utils.smartquotes`` + + * - ``sphinx.util.typing.DirectiveOption`` + - 4.0 + - 6.0 + - N/A + + * - pending_xref node for viewcode extension + - 3.5 + - 5.0 + - ``sphinx.ext.viewcode.viewcode_anchor`` + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.node_line_or_0()`` + - 3.5 + - 5.0 + - ``sphinx.util.nodes.get_node_line()`` + + * - ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.importer.get_module_members()`` + - 3.5 + - 5.0 + - ``sphinx.ext.autodoc.ModuleDocumenter.get_module_members()`` + + * - ``sphinx.ext.autosummary.generate._simple_info()`` + - 3.5 + - 5.0 + - :ref:`logging-api` + + * - ``sphinx.ext.autosummary.generate._simple_warn()`` + - 3.5 + - 5.0 + - :ref:`logging-api` + + * - ``sphinx.writers.html.HTMLTranslator.permalink_text`` + - 3.5 + - 5.0 + - :confval:`html_permalinks_icon` + + * - ``sphinx.writers.html5.HTML5Translator.permalink_text`` + - 3.5 + - 5.0 + - :confval:`html_permalinks_icon` + + * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()`` + - 3.4 + - 5.0 + - N/A + + * - The ``no_docstring`` argument of + ``sphinx.ext.autodoc.Documenter.add_content()`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.Documenter.get_doc()`` + + * - ``sphinx.ext.autodoc.Documenter.get_object_members()`` + - 3.4 + - 6.0 + - ``sphinx.ext.autodoc.ClassDocumenter.get_object_members()`` + + * - ``sphinx.ext.autodoc.DataDeclarationDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.GenericAliasDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.InstanceAttributeDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.AttributeDocumenter`` + + * - ``sphinx.ext.autodoc.SlotsAttributeDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.AttributeDocumenter`` + + * - ``sphinx.ext.autodoc.TypeVarDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter`` + - 3.5 + - 5.0 + - ``sphinx.util.logging`` + + * - ``sphinx.ext.autodoc.importer._getannotations()`` + - 3.4 + - 4.0 + - ``sphinx.util.inspect.getannotations()`` + + * - ``sphinx.ext.autodoc.importer._getmro()`` + - 3.4 + - 4.0 + - ``sphinx.util.inspect.getmro()`` + + * - ``sphinx.pycode.ModuleAnalyzer.parse()`` + - 3.4 + - 5.0 + - ``sphinx.pycode.ModuleAnalyzer.analyze()`` + + * - ``sphinx.util.osutil.movefile()`` + - 3.4 + - 5.0 + - ``os.replace()`` + + * - ``sphinx.util.requests.is_ssl_error()`` + - 3.4 + - 5.0 + - N/A + + * - ``sphinx.builders.latex.LaTeXBuilder.usepackages`` + - 3.3 + - 5.0 + - N/A + + * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref`` + - 3.3 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter`` + - 3.3 + - 5.0 + - ``sphinx.ext.autodoc.FunctionDocumenter`` + + * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter`` + - 3.3 + - 5.0 + - ``sphinx.ext.autodoc.MethodDocumenter`` + + * - ``sphinx.ext.autodoc.members_set_option()`` + - 3.2 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.merge_special_members_option()`` + - 3.2 + - 5.0 + - ``sphinx.ext.autodoc.merge_members_option()`` + + * - ``sphinx.writers.texinfo.TexinfoWriter.desc`` + - 3.2 + - 5.0 + - ``sphinx.writers.texinfo.TexinfoWriter.descs`` + + * - The first argument for + ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` has been changed + to Sphinx object + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object + type as an argument + - 3.1 + - 5.0 + - N/A + + * - The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()`` + - 3.1 + - 5.0 + - N/A + + * - The ``template_dir`` argument of + ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` + - 3.1 + - 5.0 + - N/A + + * - The ``module`` argument of + ``sphinx.ext.autosummary.generate.find_autosummary_in_docstring()`` + - 3.0 + - 5.0 + - N/A + + * - The ``builder`` argument of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 3.1 + - 5.0 + - N/A + + * - The ``template_dir`` argument of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()`` + - 3.1 + - 5.0 + - N/A + + * - The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()`` + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.util.rpartition()`` + - 3.1 + - 5.0 + - ``str.rpartition()`` + + * - ``desc_signature['first']`` + - + - 3.0 + - N/A + + * - ``sphinx.directives.DescDirective`` + - 3.0 + - 5.0 + - ``sphinx.directives.ObjectDescription`` + + * - ``sphinx.domains.std.StandardDomain.add_object()`` + - 3.0 + - 5.0 + - ``sphinx.domains.std.StandardDomain.note_object()`` + + * - ``sphinx.domains.python.PyDecoratorMixin`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.get_documenters()`` + - 3.0 + - 5.0 + - ``sphinx.registry.documenters`` + + * - ``sphinx.ext.autosummary.process_autosummary_toc()`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.parsers.Parser.app`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.testing.path.Path.text()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_text()`` + + * - ``sphinx.testing.path.Path.bytes()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_bytes()`` + + * - ``sphinx.util.inspect.getargspec()`` + - 3.0 + - 5.0 + - ``inspect.getargspec()`` + + * - ``sphinx.writers.latex.LaTeXWriter.format_docclass()`` + - 3.0 + - 5.0 + - LaTeX Themes + + * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.directives.other.Index`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDirective`` + + * - ``sphinx.environment.temp_data['gloss_entries']`` + - 2.4 + - 4.0 + - ``documents.nameids`` + + * - ``sphinx.environment.BuildEnvironment.indexentries`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDomain`` + + * - ``sphinx.environment.collectors.indexentries.IndexEntriesCollector`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDomain`` + + * - ``sphinx.io.FiletypeNotFoundError`` + - 2.4 + - 4.0 + - ``sphinx.errors.FiletypeNotFoundError`` + + * - ``sphinx.ext.apidoc.INITPY`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.shall_skip()`` + - 2.4 + - 4.0 + - ``sphinx.ext.apidoc.is_skipped_package`` + + * - ``sphinx.io.get_filetype()`` + - 2.4 + - 4.0 + - ``sphinx.util.get_filetype()`` + + * - ``sphinx.pycode.ModuleAnalyzer.encoding`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.roles.Index`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexRole`` + + * - ``sphinx.util.detect_encoding()`` + - 2.4 + - 4.0 + - ``tokenize.detect_encoding()`` + + * - ``sphinx.util.get_module_source()`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.util.inspect.Signature`` + - 2.4 + - 4.0 + - ``sphinx.util.inspect.signature`` and + ``sphinx.util.inspect.stringify_signature()`` + + * - ``sphinx.util.inspect.safe_getmembers()`` + - 2.4 + - 4.0 + - ``inspect.getmembers()`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.author`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname`` + - 2.4 + - 4.0 + - ``document['contentsname']`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.docclass`` + - 2.4 + - 4.0 + - ``document['docclass']`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.docname`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.title`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.ADDITIONAL_SETTINGS`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.ADDITIONAL_SETTINGS`` + + * - ``sphinx.writers.latex.DEFAULT_SETTINGS`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.DEFAULT_SETTINGS`` + + * - ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG`` + + * - ``sphinx.builders.gettext.POHEADER`` + - 2.3 + - 4.0 + - ``sphinx/templates/gettext/message.pot_t`` (template file) + + * - ``sphinx.io.SphinxStandaloneReader.app`` + - 2.3 + - 4.0 + - ``sphinx.io.SphinxStandaloneReader.setup()`` + + * - ``sphinx.io.SphinxStandaloneReader.env`` + - 2.3 + - 4.0 + - ``sphinx.io.SphinxStandaloneReader.setup()`` + + * - ``sphinx.util.texescape.tex_escape_map`` + - 2.3 + - 4.0 + - ``sphinx.util.texescape.escape()`` + + * - ``sphinx.util.texescape.tex_hl_escape_map_new`` + - 2.3 + - 4.0 + - ``sphinx.util.texescape.hlescape()`` + + * - ``sphinx.writers.latex.LaTeXTranslator.no_contractions`` + - 2.3 + - 4.0 + - N/A + + * - ``sphinx.domains.math.MathDomain.add_equation()`` + - 2.2 + - 4.0 + - ``sphinx.domains.math.MathDomain.note_equation()`` + + * - ``sphinx.domains.math.MathDomain.get_next_equation_number()`` + - 2.2 + - 4.0 + - ``sphinx.domains.math.MathDomain.note_equation()`` + + * - The ``info`` and ``warn`` arguments of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 2.2 + - 4.0 + - ``logging.info()`` and ``logging.warning()`` + + * - ``sphinx.ext.autosummary.generate._simple_info()`` + - 2.2 + - 4.0 + - ``logging.info()`` + + * - ``sphinx.ext.autosummary.generate._simple_warn()`` + - 2.2 + - 4.0 + - ``logging.warning()`` + + * - ``sphinx.ext.todo.merge_info()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.process_todo_nodes()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.process_todos()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.purge_todos()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.builders._epub_base.EpubBuilder.esc()`` + - 2.1 + - 4.0 + - ``html.escape()`` + + * - ``sphinx.directives.Acks`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Acks`` + + * - ``sphinx.directives.Author`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Author`` + + * - ``sphinx.directives.Centered`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Centered`` + + * - ``sphinx.directives.Class`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Class`` + + * - ``sphinx.directives.CodeBlock`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.CodeBlock`` + + * - ``sphinx.directives.Figure`` + - 2.1 + - 4.0 + - ``sphinx.directives.patches.Figure`` + + * - ``sphinx.directives.HList`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.HList`` + + * - ``sphinx.directives.Highlight`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.Highlight`` + + * - ``sphinx.directives.Include`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Include`` + + * - ``sphinx.directives.Index`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Index`` + + * - ``sphinx.directives.LiteralInclude`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.LiteralInclude`` + + * - ``sphinx.directives.Meta`` + - 2.1 + - 4.0 + - ``sphinx.directives.patches.Meta`` + + * - ``sphinx.directives.Only`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Only`` + + * - ``sphinx.directives.SeeAlso`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.SeeAlso`` + + * - ``sphinx.directives.TabularColumns`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.TabularColumns`` + + * - ``sphinx.directives.TocTree`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.TocTree`` + + * - ``sphinx.directives.VersionChange`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.VersionChange`` + + * - ``sphinx.domains.python.PyClassmember`` + - 2.1 + - 4.0 + - ``sphinx.domains.python.PyAttribute``, + ``sphinx.domains.python.PyMethod``, + ``sphinx.domains.python.PyClassMethod``, + ``sphinx.domains.python.PyObject`` and + ``sphinx.domains.python.PyStaticMethod`` + + * - ``sphinx.domains.python.PyModulelevel`` + - 2.1 + - 4.0 + - ``sphinx.domains.python.PyFunction``, + ``sphinx.domains.python.PyObject`` and + ``sphinx.domains.python.PyVariable`` + + * - ``sphinx.domains.std.StandardDomain._resolve_citation_xref()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.resolve_xref()`` + + * - ``sphinx.domains.std.StandardDomain.note_citations()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.note_citation()`` + + * - ``sphinx.domains.std.StandardDomain.note_citation_refs()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.note_citation_reference()`` + + * - ``sphinx.domains.std.StandardDomain.note_labels()`` + - 2.1 + - 4.0 + - ``sphinx.domains.std.StandardDomain.process_doc()`` + + * - ``sphinx.domains.js.JSObject.display_prefix`` + - + - 4.3 + - ``sphinx.domains.js.JSObject.get_display_prefix()`` + + * - ``sphinx.environment.NoUri`` + - 2.1 + - 3.0 + - ``sphinx.errors.NoUri`` + + * - ``sphinx.ext.apidoc.format_directive()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.format_heading()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.makename()`` + - 2.1 + - 4.0 + - ``sphinx.ext.apidoc.module_join()`` + + * - ``sphinx.ext.autodoc.importer.MockFinder`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.MockFinder`` + + * - ``sphinx.ext.autodoc.importer.MockLoader`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.MockLoader`` + + * - ``sphinx.ext.autodoc.importer.mock()`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.mock()`` + + * - ``sphinx.ext.autosummary.autolink_role()`` + - 2.1 + - 4.0 + - ``sphinx.ext.autosummary.AutoLink`` + + * - ``sphinx.ext.imgmath.DOC_BODY`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.imgmath.DOC_BODY_PREVIEW`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.imgmath.DOC_HEAD`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.transforms.CitationReferences`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationReferenceTransform`` + + * - ``sphinx.transforms.SmartQuotesSkipper`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDefinitionTransform`` + + * - ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()`` + - 2.1 + - 4.0 + - ``sphinx.directives.ObjectDescription.get_field_type_map()`` + + * - ``sphinx.util.node.find_source_node()`` + - 2.1 + - 4.0 + - ``sphinx.util.node.get_node_source()`` + + * - ``sphinx.util.i18n.find_catalog()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.docname_to_domain()`` + + * - ``sphinx.util.i18n.find_catalog_files()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.CatalogRepository`` + + * - ``sphinx.util.i18n.find_catalog_source_files()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.CatalogRepository`` + + * - ``encoding`` argument of ``autodoc.Documenter.get_doc()``, + ``autodoc.DocstringSignatureMixin.get_doc()``, + ``autodoc.DocstringSignatureMixin._find_signature()``, and + ``autodoc.ClassDocumenter.get_doc()`` + - 2.0 + - 4.0 + - N/A + + * - arguments of ``EpubBuilder.build_mimetype()``, + ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``, + ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()`` + - 2.0 + - 4.0 + - N/A + + * - arguments of ``Epub3Builder.build_navigation_doc()`` + - 2.0 + - 4.0 + - N/A + + * - ``nodetype`` argument of + ``sphinx.search.WordCollector.is_meta_keywords()`` + - 2.0 + - 4.0 + - N/A + + * - ``suffix`` argument of ``BuildEnvironment.doc2path()`` + - 2.0 + - 4.0 + - N/A + + * - string style ``base`` argument of ``BuildEnvironment.doc2path()`` + - 2.0 + - 4.0 + - ``os.path.join()`` + + * - ``sphinx.addnodes.abbreviation`` + - 2.0 + - 4.0 + - ``docutils.nodes.abbreviation`` + + * - ``sphinx.builders.applehelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.applehelp`` + + * - ``sphinx.builders.devhelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.devhelp`` + + * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()`` + - 2.0 + - 4.0 + - ``sphinx.builders.epub3.validate_config_values()`` + + * - ``sphinx.builders.html.JSONHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.JSONHTMLBuilder`` + + * - ``sphinx.builders.html.PickleHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.PickleHTMLBuilder`` + + * - ``sphinx.builders.html.SerializingHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.SerializingHTMLBuilder`` + + * - ``sphinx.builders.html.SingleFileHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder`` + + * - ``sphinx.builders.html.WebHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.PickleHTMLBuilder`` + + * - ``sphinx.builders.htmlhelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.htmlhelp`` + + * - ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()`` + - 2.0 + - 4.0 + - ``open()`` + + * - ``sphinx.builders.qthelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.qthelp`` + + * - ``sphinx.cmd.quickstart.term_decode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.cmd.quickstart.TERM_ENCODING`` + - 2.0 + - 4.0 + - ``sys.stdin.encoding`` + + * - ``sphinx.config.check_unicode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.config.string_classes`` + - 2.0 + - 4.0 + - ``[str]`` + + * - ``sphinx.domains.cpp.DefinitionError.description`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.domains.cpp.NoOldIdError.description`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.ext.autosummary.Autosummary.warn()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.genopt`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.warnings`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.result`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.doctest.doctest_encode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.jsmath`` + - 2.0 + - 4.0 + - ``sphinxcontrib.jsmath`` + + * - ``sphinx.roles.abbr_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.Abbreviation`` + + * - ``sphinx.roles.emph_literal_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.EmphasizedLiteral`` + + * - ``sphinx.roles.menusel_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.GUILabel`` or ``sphinx.roles.MenuSelection`` + + * - ``sphinx.roles.index_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.Index`` + + * - ``sphinx.roles.indexmarkup_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.PEP`` or ``sphinx.roles.RFC`` + + * - ``sphinx.testing.util.remove_unicode_literal()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.attrdict`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.force_decode()`` + - 2.0 + - 5.0 + - N/A + + * - ``sphinx.util.get_matching_docs()`` + - 2.0 + - 4.0 + - ``sphinx.util.get_matching_files()`` + + * - ``sphinx.util.inspect.Parameter`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.util.jsonimpl`` + - 2.0 + - 4.0 + - ``sphinxcontrib.serializinghtml.jsonimpl`` + + * - ``sphinx.util.osutil.EEXIST`` + - 2.0 + - 4.0 + - ``errno.EEXIST`` or ``FileExistsError`` + + * - ``sphinx.util.osutil.EINVAL`` + - 2.0 + - 4.0 + - ``errno.EINVAL`` + + * - ``sphinx.util.osutil.ENOENT`` + - 2.0 + - 4.0 + - ``errno.ENOENT`` or ``FileNotFoundError`` + + * - ``sphinx.util.osutil.EPIPE`` + - 2.0 + - 4.0 + - ``errno.ENOENT`` or ``BrokenPipeError`` + + * - ``sphinx.util.osutil.walk()`` + - 2.0 + - 4.0 + - ``os.walk()`` + + * - ``sphinx.util.pycompat.NoneType`` + - 2.0 + - 4.0 + - ``sphinx.util.typing.NoneType`` + + * - ``sphinx.util.pycompat.TextIOWrapper`` + - 2.0 + - 4.0 + - ``io.TextIOWrapper`` + + * - ``sphinx.util.pycompat.UnicodeMixin`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.pycompat.htmlescape()`` + - 2.0 + - 4.0 + - ``html.escape()`` + + * - ``sphinx.util.pycompat.indent()`` + - 2.0 + - 4.0 + - ``textwrap.indent()`` + + * - ``sphinx.util.pycompat.sys_encoding`` + - 2.0 + - 4.0 + - ``sys.getdefaultencoding()`` + + * - ``sphinx.util.pycompat.terminal_safe()`` + - 2.0 + - 4.0 + - ``sphinx.util.console.terminal_safe()`` + + * - ``sphinx.util.pycompat.u`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.PeekableIterator`` + - 2.0 + - 4.0 + - N/A + + * - Omitting the ``filename`` argument in an overriddent + ``IndexBuilder.feed()`` method. + - 2.0 + - 4.0 + - ``IndexBuilder.feed(docname, filename, title, doctree)`` + + * - ``sphinx.writers.latex.ExtBabel`` + - 2.0 + - 4.0 + - ``sphinx.builders.latex.util.ExtBabel`` + + * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.application.Sphinx._setting_up_extension`` + - 2.0 + - 3.0 + - N/A + + * - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.ext.autodoc.importer._MockImporter`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxBaseFileInput`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxFileInput.supported`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxRSTFileInput`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.registry.SphinxComponentRegistry.add_source_input()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()`` + - 2.0 + - 4.0 + - N/A + + * - :rst:dir:`highlightlang` + - 1.8 + - 4.0 + - :rst:dir:`highlight` + + * - :meth:`~sphinx.application.Sphinx.add_stylesheet()` + - 1.8 + - 6.0 + - :meth:`~sphinx.application.Sphinx.add_css_file()` + + * - :meth:`~sphinx.application.Sphinx.add_javascript()` + - 1.8 + - 4.0 + - :meth:`~sphinx.application.Sphinx.add_js_file()` + + * - :confval:`autodoc_default_flags` + - 1.8 + - 4.0 + - :confval:`autodoc_default_options` + + * - ``content`` arguments of ``sphinx.util.image.guess_mimetype()`` + - 1.8 + - 3.0 + - N/A + + * - ``gettext_compact`` arguments of + ``sphinx.util.i18n.find_catalog_source_files()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxI18nReader.line`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.directives.other.VersionChanges`` + - 1.8 + - 3.0 + - ``sphinx.domains.changeset.VersionChanges`` + + * - ``sphinx.highlighting.PygmentsBridge.unhighlight()`` + - 1.8 + - 3.0 + - N/A + + * - ``trim_doctest_flags`` arguments of + ``sphinx.highlighting.PygmentsBridge`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase.MathDomain`` + - 1.8 + - 3.0 + - ``sphinx.domains.math.MathDomain`` + + * - ``sphinx.ext.mathbase.MathDirective`` + - 1.8 + - 3.0 + - ``sphinx.directives.patches.MathDirective`` + + * - ``sphinx.ext.mathbase.math_role()`` + - 1.8 + - 3.0 + - ``docutils.parsers.rst.roles.math_role()`` + + * - ``sphinx.ext.mathbase.setup_math()`` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()` + + * - ``sphinx.ext.mathbase.is_in_section_title()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase.get_node_equation_number()`` + - 1.8 + - 3.0 + - ``sphinx.util.math.get_node_equation_number()`` + + * - ``sphinx.ext.mathbase.wrap_displaymath()`` + - 1.8 + - 3.0 + - ``sphinx.util.math.wrap_displaymath()`` + + * - ``sphinx.ext.mathbase.math`` (node) + - 1.8 + - 3.0 + - ``docutils.nodes.math`` + + * - ``sphinx.ext.mathbase.displaymath`` (node) + - 1.8 + - 3.0 + - ``docutils.nodes.math_block`` + + * - ``sphinx.ext.mathbase.eqref`` (node) + - 1.8 + - 3.0 + - ``sphinx.builders.latex.nodes.math_reference`` + + * - ``viewcode_import`` (config value) + - 1.8 + - 3.0 + - :confval:`viewcode_follow_imported_members` + + * - ``sphinx.writers.latex.Table.caption_footnotetexts`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.Table.header_footnotetexts`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.footnotestack`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.next_section_ids`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.bibitems`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlang()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlang()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()`` + - 1.8 + - 3.0 + - Nothing + + * - ``sphinx.application.CONFIG_FILENAME`` + - 1.8 + - 3.0 + - ``sphinx.config.CONFIG_FILENAME`` + + * - ``Config.check_unicode()`` + - 1.8 + - 3.0 + - ``sphinx.config.check_unicode()`` + + * - ``Config.check_types()`` + - 1.8 + - 3.0 + - ``sphinx.config.check_confval_types()`` + + * - ``dirname``, ``filename`` and ``tags`` arguments of + ``Config.__init__()`` + - 1.8 + - 3.0 + - ``Config.read()`` + + * - The value of :confval:`html_search_options` + - 1.8 + - 3.0 + - see :confval:`html_search_options` + + * - ``sphinx.versioning.prepare()`` + - 1.8 + - 3.0 + - ``sphinx.versioning.UIDTransform`` + + * - ``Sphinx.override_domain()`` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_domain()` + + * - ``Sphinx.import_object()`` + - 1.8 + - 3.0 + - ``sphinx.util.import_object()`` + + * - ``suffix`` argument of + :meth:`~sphinx.application.Sphinx.add_source_parser()` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_source_suffix()` + + + * - ``BuildEnvironment.load()`` + - 1.8 + - 3.0 + - ``pickle.load()`` + + * - ``BuildEnvironment.loads()`` + - 1.8 + - 3.0 + - ``pickle.loads()`` + + * - ``BuildEnvironment.frompickle()`` + - 1.8 + - 3.0 + - ``pickle.load()`` + + * - ``BuildEnvironment.dump()`` + - 1.8 + - 3.0 + - ``pickle.dump()`` + + * - ``BuildEnvironment.dumps()`` + - 1.8 + - 3.0 + - ``pickle.dumps()`` + + * - ``BuildEnvironment.topickle()`` + - 1.8 + - 3.0 + - ``pickle.dump()`` + + * - ``BuildEnvironment._nitpick_ignore`` + - 1.8 + - 3.0 + - :confval:`nitpick_ignore` + + * - ``BuildEnvironment.versionchanges`` + - 1.8 + - 3.0 + - N/A + + * - ``BuildEnvironment.update()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment.read_doc()`` + - 1.8 + - 3.0 + - ``Builder.read_doc()`` + + * - ``BuildEnvironment._read_serial()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment._read_parallel()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment.write_doctree()`` + - 1.8 + - 3.0 + - ``Builder.write_doctree()`` + + * - ``BuildEnvironment.note_versionchange()`` + - 1.8 + - 3.0 + - ``ChangesDomain.note_changeset()`` + + * - ``warn()`` (template helper function) + - 1.8 + - 3.0 + - ``warning()`` + + * - :confval:`source_parsers` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_source_parser()` + + * - ``sphinx.util.docutils.directive_helper()`` + - 1.8 + - 3.0 + - ``Directive`` class of docutils + + * - ``sphinx.cmdline`` + - 1.8 + - 3.0 + - ``sphinx.cmd.build`` + + * - ``sphinx.make_mode`` + - 1.8 + - 3.0 + - ``sphinx.cmd.make_mode`` + + * - ``sphinx.locale.l_()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.locale.lazy_gettext()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.locale.mygettext()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.util.copy_static_entry()`` + - 1.5 + - 3.0 + - ``sphinx.util.fileutil.copy_asset()`` + + * - ``sphinx.build_main()`` + - 1.7 + - 2.0 + - ``sphinx.cmd.build.build_main()`` + + * - ``sphinx.ext.intersphinx.debug()`` + - 1.7 + - 2.0 + - ``sphinx.ext.intersphinx.inspect_main()`` + + * - ``sphinx.ext.autodoc.format_annotation()`` + - 1.7 + - 2.0 + - ``sphinx.util.inspect.Signature`` + + * - ``sphinx.ext.autodoc.formatargspec()`` + - 1.7 + - 2.0 + - ``sphinx.util.inspect.Signature`` + + * - ``sphinx.ext.autodoc.AutodocReporter`` + - 1.7 + - 2.0 + - ``sphinx.util.docutils.switch_source_input()`` + + * - ``sphinx.ext.autodoc.add_documenter()`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + + * - ``sphinx.ext.autodoc.AutoDirective._register`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + + * - ``AutoDirective._special_attrgetters`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()` + + * - ``Sphinx.warn()``, ``Sphinx.info()`` + - 1.6 + - 2.0 + - :ref:`logging-api` + + * - ``BuildEnvironment.set_warnfunc()`` + - 1.6 + - 2.0 + - :ref:`logging-api` + + * - ``BuildEnvironment.note_toctree()`` + - 1.6 + - 2.0 + - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.get_toc_for()`` + - 1.6 + - 2.0 + - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.get_toctree_for()`` + - 1.6 + - 2.0 + - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.create_index()`` + - 1.6 + - 2.0 + - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``) + + * - ``sphinx.websupport`` + - 1.6 + - 2.0 + - `sphinxcontrib-websupport`_ + + .. _sphinxcontrib-websupport: https://pypi.org/project/sphinxcontrib-websupport/ + + * - ``StandaloneHTMLBuilder.css_files`` + - 1.6 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_stylesheet()` + + * - ``document.settings.gettext_compact`` + - 1.8 + - 1.8 + - :confval:`gettext_compact` + + * - ``Sphinx.status_iterator()`` + - 1.6 + - 1.7 + - ``sphinx.util.status_iterator()`` + + * - ``Sphinx.old_status_iterator()`` + - 1.6 + - 1.7 + - ``sphinx.util.old_status_iterator()`` + + * - ``Sphinx._directive_helper()`` + - 1.6 + - 1.7 + - ``sphinx.util.docutils.directive_helper()`` + + * - ``sphinx.util.compat.Directive`` + - 1.6 + - 1.7 + - ``docutils.parsers.rst.Directive`` + + * - ``sphinx.util.compat.docutils_version`` + - 1.6 + - 1.7 + - ``sphinx.util.docutils.__version_info__`` + +.. note:: On deprecating on public APIs (internal functions and classes), + we also follow the policy as much as possible. diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst new file mode 100644 index 0000000..d70b5db --- /dev/null +++ b/doc/extdev/domainapi.rst @@ -0,0 +1,32 @@ +.. _domain-api: + +Domain API +========== + +.. module:: sphinx.domains + +.. autoclass:: Domain + :members: + +.. autoclass:: ObjType + +.. autoclass:: Index + :members: + +.. module:: sphinx.directives + +.. autoclass:: ObjectDescription + :members: + :private-members: _toc_entry_name, _object_hierarchy_parts + +Python Domain +------------- + +.. module:: sphinx.domains.python + +.. autoclass:: PythonDomain + + .. autoattribute:: objects + .. autoattribute:: modules + .. automethod:: note_object + .. automethod:: note_module diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst new file mode 100644 index 0000000..d7ec239 --- /dev/null +++ b/doc/extdev/envapi.rst @@ -0,0 +1,58 @@ +Build environment API +===================== + +.. module:: sphinx.environment + +.. class:: BuildEnvironment + + **Attributes** + + .. attribute:: app + + Reference to the :class:`.Sphinx` (application) object. + + .. attribute:: config + + Reference to the :class:`.Config` object. + + .. attribute:: project + + Target project. See :class:`.Project`. + + .. attribute:: srcdir + + Source directory. + + .. attribute:: doctreedir + + Directory for storing pickled doctrees. + + .. attribute:: events + + An :class:`.EventManager` object. + + .. attribute:: found_docs + + A set of all existing docnames. + + .. attribute:: metadata + + Dictionary mapping docnames to "metadata" (see :ref:`metadata`). + + .. attribute:: titles + + Dictionary mapping docnames to the docutils node for their main title. + + .. autoattribute:: docname + + **Utility methods** + + .. automethod:: doc2path + + .. automethod:: relfn2path + + .. automethod:: note_dependency + + .. automethod:: new_serialno + + .. automethod:: note_reread diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst new file mode 100644 index 0000000..6b32b8b --- /dev/null +++ b/doc/extdev/i18n.rst @@ -0,0 +1,97 @@ +.. _i18n-api: + +i18n API +======== + +.. currentmodule:: sphinx.locale + +.. autofunction:: init + +.. autofunction:: init_console + +.. autofunction:: get_translation + +.. autofunction:: _ + +.. autofunction:: __ + + +.. _ext-i18n: + +Extension internationalization (`i18n`) and localization (`l10n`) using i18n API +-------------------------------------------------------------------------------- + +.. versionadded:: 1.8 + +An extension may naturally come with message translations. This is briefly +summarized in :func:`sphinx.locale.get_translation` help. + +In practice, you have to: + +#. Choose a name for your message catalog, which must be unique. Usually + the name of your extension is used for the name of message catalog. + +#. Mark in your extension sources all messages as translatable, via + :func:`sphinx.locale.get_translation` function, usually renamed ``_()``, + e.g.: + + .. code-block:: python + :caption: src/__init__.py + + from sphinx.locale import get_translation + + MESSAGE_CATALOG_NAME = 'myextension' + _ = get_translation(MESSAGE_CATALOG_NAME) + + translated_text = _('Hello Sphinx!') + +#. Set up your extension to be aware of its dedicated translations: + + .. code-block:: python + :caption: src/__init__.py + + def setup(app): + package_dir = path.abspath(path.dirname(__file__)) + locale_dir = os.path.join(package_dir, 'locales') + app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir) + +#. Generate message catalog template ``*.pot`` file, usually in ``locale/`` + source directory, for example via `Babel`_: + + .. code-block:: console + + $ pybabel extract --output=src/locale/myextension.pot src/ + +#. Create message catalogs (``*.po``) for each language which your extension + will provide localization, for example via `Babel`_: + + .. code-block:: console + + $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR + +#. Translate message catalogs for each language manually + +#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_: + + .. code-block:: console + + $ pybabel compile --directory=src/locale --domain=myextension + +#. Ensure that message catalog files are distributed when your package will + be installed, by adding equivalent line in your extension ``MANIFEST.in``: + + .. code-block:: ini + :caption: MANIFEST.in + + recursive-include src *.pot *.po *.mo + + +When the messages on your extension has been changed, you need to also update +message catalog template and message catalogs, for example via `Babel`_: + +.. code-block:: console + + $ pybabel extract --output=src/locale/myextension.pot src/ + $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale + +.. _Babel: https://babel.pocoo.org/ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst new file mode 100644 index 0000000..014a806 --- /dev/null +++ b/doc/extdev/index.rst @@ -0,0 +1,218 @@ +.. _dev-extensions: + +Developing extensions for Sphinx +================================ + +Since many projects will need special features in their documentation, Sphinx +is designed to be extensible on several levels. + +Here are a few things you can do in an extension: + +* Add new :term:`builder`\s to support new output formats or actions on the + parsed documents. +* Register custom reStructuredText roles and directives, extending the markup + using the :doc:`markupapi`. +* Add custom code to so-called "hook points" at strategic places throughout the + build process, allowing you to register a hook and run specialized code. + For example, see the :ref:`events`. + +An extension is simply a Python module with a ``setup()`` function. A user +activates the extension by placing the extension's module name +(or a sub-module) in their :confval:`extensions` configuration value. + +When :program:`sphinx-build` is executed, Sphinx will attempt to import each +module that is listed, and execute ``yourmodule.setup(app)``. This +function is used to prepare the extension (e.g., by executing Python code), +linking resources that Sphinx uses in the build process (like CSS or HTML +files), and notifying Sphinx of everything the extension offers (such +as directive or role definitions). The ``app`` argument is an instance of +:class:`.Sphinx` and gives you control over most aspects of the Sphinx build. + +.. note:: + + The configuration file itself can be treated as an extension if it + contains a ``setup()`` function. All other extensions to load must be + listed in the :confval:`extensions` configuration value. + +The rest of this page describes some high-level aspects of developing +extensions and various parts of Sphinx's behavior that you can control. +For some examples of how extensions can be built and used to control different +parts of Sphinx, see the :ref:`extension-tutorials-index`. + +.. _important-objects: + +Important objects +----------------- + +There are several key objects whose API you will use while writing an +extension. These are: + +**Application** + The application object (usually called ``app``) is an instance of + :class:`.Sphinx`. It controls most high-level functionality, such as the + setup of extensions, event dispatching and producing output (logging). + + If you have the environment object, the application is available as + ``env.app``. + +**Environment** + The build environment object (usually called ``env``) is an instance of + :class:`.BuildEnvironment`. It is responsible for parsing the source + documents, stores all metadata about the document collection and is + serialized to disk after each build. + + Its API provides methods to do with access to metadata, resolving references, + etc. It can also be used by extensions to cache information that should + persist for incremental rebuilds. + + If you have the application or builder object, the environment is available + as ``app.env`` or ``builder.env``. + +**Builder** + The builder object (usually called ``builder``) is an instance of a specific + subclass of :class:`.Builder`. Each builder class knows how to convert the + parsed documents into an output format, or otherwise process them (e.g. check + external links). + + If you have the application object, the builder is available as + ``app.builder``. + +**Config** + The config object (usually called ``config``) provides the values of + configuration values set in :file:`conf.py` as attributes. It is an instance + of :class:`.Config`. + + The config is available as ``app.config`` or ``env.config``. + +To see an example of use of these objects, refer to +:doc:`../development/tutorials/index`. + +.. _build-phases: + +Build Phases +------------ + +One thing that is vital in order to understand extension mechanisms is the way +in which a Sphinx project is built: this works in several phases. + +**Phase 0: Initialization** + +In this phase, almost nothing of interest to us happens. The source +directory is searched for source files, and extensions are initialized. +Should a stored build environment exist, it is loaded, otherwise a new one is +created. + +**Phase 1: Reading** + +In Phase 1, all source files (and on subsequent builds, those that are new or +changed) are read and parsed. This is the phase where directives and roles +are encountered by docutils, and the corresponding code is executed. The +output of this phase is a *doctree* for each source file; that is a tree of +docutils nodes. For document elements that aren't fully known until all +existing files are read, temporary nodes are created. + +There are nodes provided by docutils, which are documented `in the docutils +documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__. +Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`. + +During reading, the build environment is updated with all meta- and cross +reference data of the read documents, such as labels, the names of headings, +described Python objects and index entries. This will later be used to +replace the temporary nodes. + +The parsed doctrees are stored on the disk, because it is not possible to +hold all of them in memory. + +**Phase 2: Consistency checks** + +Some checking is done to ensure no surprises in the built documents. + +**Phase 3: Resolving** + +Now that the metadata and cross-reference data of all existing documents is +known, all temporary nodes are replaced by nodes that can be converted into +output using components called transforms. For example, links are created +for object references that exist, and simple literal nodes are created for +those that don't. + +**Phase 4: Writing** + +This phase converts the resolved doctrees to the desired output format, such +as HTML or LaTeX. This happens via a so-called docutils writer that visits +the individual nodes of each doctree and produces some output in the process. + +.. note:: + + Some builders deviate from this general build plan, for example, the builder + that checks external links does not need anything more than the parsed + doctrees and therefore does not have phases 2--4. + +To see an example of application, refer to :doc:`../development/tutorials/todo`. + +.. _ext-metadata: + +Extension metadata +------------------ + +.. versionadded:: 1.3 + +The ``setup()`` function can return a dictionary. This is treated by Sphinx +as metadata of the extension. Metadata keys currently recognized are: + +* ``'version'``: a string that identifies the extension version. It is used for + extension version requirement checking (see :confval:`needs_extensions`) and + informational purposes. If not given, ``"unknown version"`` is substituted. +* ``'env_version'``: an integer that identifies the version of env data + structure if the extension stores any data to environment. It is used to + detect the data structure has been changed from last build. The extensions + have to increment the version when data structure has changed. If not given, + Sphinx considers the extension does not stores any data to environment. +* ``'parallel_read_safe'``: a boolean that specifies if parallel reading of + source files can be used when the extension is loaded. It defaults to + ``False``, i.e. you have to explicitly specify your extension to be + parallel-read-safe after checking that it is. + + .. note:: The *parallel-read-safe* extension must satisfy the following + conditions: + + * The core logic of the extension is parallelly executable during + the reading phase. + * It has event handlers for :event:`env-merge-info` and + :event:`env-purge-doc` events if it stores data to the build + environment object (env) during the reading phase. + +* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of + output files can be used when the extension is loaded. Since extensions + usually don't negatively influence the process, this defaults to ``True``. + + .. note:: The *parallel-write-safe* extension must satisfy the following + conditions: + + * The core logic of the extension is parallelly executable during + the writing phase. + + +APIs used for writing extensions +-------------------------------- + +These sections provide a more complete description of the tools at your +disposal when developing Sphinx extensions. Some are core to Sphinx +(such as the :doc:`appapi`) while others trigger specific behavior +(such as the :doc:`i18n`) + +.. toctree:: + :maxdepth: 2 + + appapi + projectapi + envapi + builderapi + collectorapi + markupapi + domainapi + parserapi + nodes + logging + i18n + utils + deprecated diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst new file mode 100644 index 0000000..e6c4dc6 --- /dev/null +++ b/doc/extdev/logging.rst @@ -0,0 +1,66 @@ +.. _logging-api: + +Logging API +=========== + +.. currentmodule:: sphinx.util.logging + +.. autofunction:: getLogger(name) + +.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter) + + .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs) + + Logs a message on this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **type**, ***subtype*** + Categories of warning logs. It is used to suppress + warnings by :confval:`suppress_warnings` setting. + + **location** + Where the warning happened. It is used to include + the path and line number in each log. It allows docname, + tuple of docname and line number and nodes:: + + logger = sphinx.util.logging.getLogger(__name__) + logger.warning('Warning happened!', location='index') + logger.warning('Warning happened!', location=('chapter1/index', 10)) + logger.warning('Warning happened!', location=some_node) + + **color** + The color of logs. By default, error level logs are colored as + ``"darkred"``, critical level ones is not colored, and warning level + ones are colored as ``"red"``. + + .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs) + + Logs a message to this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **nonl** + If true, the logger does not fold lines at the end of the log message. + The default is ``False``. + + **location** + Where the message emitted. For more detail, see + :meth:`SphinxLoggerAdapter.warning`. + + **color** + The color of logs. By default, info and verbose level logs are not + colored, and debug level ones are colored as ``"darkgray"``. + +.. autofunction:: pending_logging() + +.. autofunction:: pending_warnings() + +.. autofunction:: prefixed_warnings() diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst new file mode 100644 index 0000000..8fc884d --- /dev/null +++ b/doc/extdev/markupapi.rst @@ -0,0 +1,152 @@ +Docutils markup API +=================== + +This section describes the API for adding ReST markup elements (roles and +directives). + +Roles +----- + + +Directives +---------- + +Directives are handled by classes derived from +``docutils.parsers.rst.Directive``. They have to be registered by an extension +using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`. + +.. module:: docutils.parsers.rst + +.. class:: Directive + + The markup syntax of the new directive is determined by the follow five class + attributes: + + .. autoattribute:: required_arguments + .. autoattribute:: optional_arguments + .. autoattribute:: final_argument_whitespace + .. autoattribute:: option_spec + + Option validator functions take a single parameter, the option argument + (or ``None`` if not given), and should validate it or convert it to the + proper form. They raise :exc:`ValueError` or :exc:`TypeError` to indicate + failure. + + There are several predefined and possibly useful validators in the + :mod:`docutils.parsers.rst.directives` module. + + .. autoattribute:: has_content + + New directives must implement the :meth:`run` method: + + .. method:: run() + + This method must process the directive arguments, options and content, and + return a list of Docutils/Sphinx nodes that will be inserted into the + document tree at the point where the directive was encountered. + + Instance attributes that are always set on the directive are: + + .. attribute:: name + + The directive name (useful when registering the same directive class under + multiple names). + + .. attribute:: arguments + + The arguments given to the directive, as a list. + + .. attribute:: options + + The options given to the directive, as a dictionary mapping option names + to validated/converted values. + + .. attribute:: content + + The directive content, if given, as a :class:`.ViewList`. + + .. attribute:: lineno + + The absolute line number on which the directive appeared. This is not + always a useful value; use :attr:`srcline` instead. + + .. attribute:: content_offset + + Internal offset of the directive content. Used when calling + ``nested_parse`` (see below). + + .. attribute:: block_text + + The string containing the entire directive. + + .. attribute:: state + state_machine + + The state and state machine which controls the parsing. Used for + ``nested_parse``. + + +ViewLists +^^^^^^^^^ + +Docutils represents document source lines in a class +``docutils.statemachine.ViewList``. This is a list with extended functionality +-- for one, slicing creates views of the original list, and also the list +contains information about the source line numbers. + +The :attr:`Directive.content` attribute is a ViewList. If you generate content +to be parsed as ReST, you have to create a ViewList yourself. Important for +content generation are the following points: + +* The constructor takes a list of strings (lines) and a source (document) name. + +* The ``.append()`` method takes a line and a source name as well. + + +Parsing directive content as ReST +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Many directives will contain more markup that must be parsed. To do this, use +one of the following APIs from the :meth:`Directive.run` method: + +* ``self.state.nested_parse`` +* :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in + the parsed content. + +Both APIs parse the content into a given node. They are used like this:: + + node = docutils.nodes.paragraph() + # either + nested_parse_with_titles(self.state, self.result, node) + # or + self.state.nested_parse(self.result, 0, node) + +.. note:: + + ``sphinx.util.docutils.switch_source_input()`` allows to change a target file + during nested_parse. It is useful to mixed contents. For example, ``sphinx. + ext.autodoc`` uses it to parse docstrings:: + + from sphinx.util.docutils import switch_source_input + + # Switch source_input between parsing content. + # Inside this context, all parsing errors and warnings are reported as + # happened in new source_input (in this case, ``self.result``). + with switch_source_input(self.state, self.result): + node = docutils.nodes.paragraph() + self.state.nested_parse(self.result, 0, node) + + .. deprecated:: 1.7 + + Until Sphinx-1.6, ``sphinx.ext.autodoc.AutodocReporter`` is used for this + purpose. For now, it is replaced by ``switch_source_input()``. + +If you don't need the wrapping node, you can use any concrete node type and +return ``node.children`` from the Directive. + + +.. seealso:: + + `Creating directives`_ HOWTO of the Docutils documentation + +.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst new file mode 100644 index 0000000..77872df --- /dev/null +++ b/doc/extdev/nodes.rst @@ -0,0 +1,71 @@ +.. _nodes: + +Doctree node classes added by Sphinx +==================================== + +.. module:: sphinx.addnodes + +Nodes for domain-specific object descriptions +--------------------------------------------- + +Top-level nodes +............... + +These nodes form the top-most levels of object descriptions. + +.. autoclass:: desc +.. autoclass:: desc_signature +.. autoclass:: desc_signature_line +.. autoclass:: desc_content +.. autoclass:: desc_inline + +Nodes for high-level structure in signatures +............................................ + +These nodes occur in in non-multiline :py:class:`desc_signature` nodes +and in :py:class:`desc_signature_line` nodes. + +.. autoclass:: desc_name +.. autoclass:: desc_addname + +.. autoclass:: desc_type +.. autoclass:: desc_returns +.. autoclass:: desc_parameterlist +.. autoclass:: desc_parameter +.. autoclass:: desc_optional +.. autoclass:: desc_annotation + +New admonition-like constructs +------------------------------ + +.. autoclass:: versionmodified +.. autoclass:: seealso + +Other paragraph-level nodes +------------------------------- + +.. autoclass:: compact_paragraph + +New inline nodes +---------------- + +.. autoclass:: index +.. autoclass:: pending_xref +.. autoclass:: pending_xref_condition +.. autoclass:: literal_emphasis +.. autoclass:: download_reference + +Special nodes +------------- + +.. autoclass:: only +.. autoclass:: meta +.. autoclass:: highlightlang + +You should not need to generate the nodes below in extensions. + +.. autoclass:: glossary +.. autoclass:: toctree +.. autoclass:: start_of_file +.. autoclass:: productionlist +.. autoclass:: production diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst new file mode 100644 index 0000000..c5db2ac --- /dev/null +++ b/doc/extdev/parserapi.rst @@ -0,0 +1,38 @@ +.. _parser-api: + +Parser API +========== + +`The docutils documentation describes`__ parsers as follows: + + The Parser analyzes the input document and creates a node tree + representation. + +__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document + +In Sphinx, the parser modules works as same as docutils. The parsers are +registered to Sphinx by extensions using Application APIs; +:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`. + +The *source suffix* is a mapping from file suffix to file type. For example, +``.rst`` file is mapped to ``'restructuredtext'`` type. Sphinx uses the +file type to looking for parsers from registered list. On searching, +Sphinx refers to the ``Parser.supported`` attribute and picks up a parser +which contains the file type in the attribute. + +The users can override the source suffix mappings using +:confval:`source_suffix` like following:: + + # a mapping from file suffix to file types + source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', + } + +You should indicate file types your parser supports. This will allow users +to configure their settings appropriately. + +.. module:: sphinx.parsers + +.. autoclass:: Parser + :members: diff --git a/doc/extdev/projectapi.rst b/doc/extdev/projectapi.rst new file mode 100644 index 0000000..238aeb4 --- /dev/null +++ b/doc/extdev/projectapi.rst @@ -0,0 +1,9 @@ +.. _project-api: + +Project API +=========== + +.. currentmodule:: sphinx.project + +.. autoclass:: Project + :members: diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst new file mode 100644 index 0000000..e842f30 --- /dev/null +++ b/doc/extdev/utils.rst @@ -0,0 +1,37 @@ +Utilities +========= + +Sphinx provides utility classes and functions to develop extensions. + +Base classes for components +--------------------------- + +These base classes are useful to allow your extensions to obtain Sphinx +components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily. + +.. note:: The subclasses of them might not work with bare docutils because they + are strongly coupled with Sphinx. + +.. autoclass:: sphinx.transforms.SphinxTransform + :members: + +.. autoclass:: sphinx.transforms.post_transforms.SphinxPostTransform + :members: + +.. autoclass:: sphinx.util.docutils.SphinxDirective + :members: + +.. autoclass:: sphinx.util.docutils.SphinxRole + :members: + +.. autoclass:: sphinx.util.docutils.ReferenceRole + :members: + +.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter + :members: + +Utility components +------------------ + +.. autoclass:: sphinx.events.EventManager + :members: |