diff options
Diffstat (limited to 'doc/extdev/appapi.rst')
| -rw-r--r-- | doc/extdev/appapi.rst | 473 |
1 files changed, 473 insertions, 0 deletions
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst new file mode 100644 index 0000000..270000b --- /dev/null +++ b/doc/extdev/appapi.rst @@ -0,0 +1,473 @@ +.. 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 + :no-index: + + .. 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:: include-read (app, relative_path, parent_docname, content) + + Emitted when a file has been read with the :dudir:`include` directive. + The *relative_path* argument is a :py:class:`~pathlib.Path` object representing + the relative path of the included file from the :term:`source directory`. + The *parent_docname* argument is the name of the document that + contains the :dudir:`include` directive. + The *source* argument is a list whose single element is + the contents of the included file. + You can process the contents and replace this item + to transform the included content, + as with the :event:`source-read` event. + + .. versionadded:: 7.2.5 + + .. seealso:: The :dudir:`include` directive and the :event:`source-read` event. + +.. 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:`~nodes.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:`~sphinx.errors.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:`~sphinx.addnodes.pending_xref` node to be resolved. + Its ``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 after reading all documents, when 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 |