diff options
Diffstat (limited to 'doc/extdev/appapi.rst')
| -rw-r--r-- | doc/extdev/appapi.rst | 288 |
1 files changed, 3 insertions, 285 deletions
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 10d030b..682db4e 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst Application API =============== @@ -137,294 +137,12 @@ The application object also provides runtime information as attributes. Directory for storing built document. - -.. _events: +.. autoattribute:: Sphinx.fresh_env_used 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 - +.. note:: Moved to :ref:`events`. Checking the Sphinx version --------------------------- |