diff options
Diffstat (limited to 'doc/extdev/appapi.rst')
| -rw-r--r-- | doc/extdev/appapi.rst | 93 |
1 files changed, 81 insertions, 12 deletions
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 0321f5e5..47584806 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -82,16 +82,31 @@ package. Register an event called *name*. This is needed to be able to emit it. +.. method:: Sphinx.set_translator(name, translator_class) + + Register or override a Docutils translator class. This is used to register + a custom output translator or to replace a builtin translator. + This allows extensions to use custom translator and define custom + nodes for the translator (see :meth:`add_node`). + + This is a API version of :confval:`html_translator_class` for all other + builders. Note that if :confval:`html_translator_class` is specified and + this API is called for html related builders, API overriding takes + precedence. + + .. versionadded:: 1.3 + .. method:: Sphinx.add_node(node, **kwds) Register a Docutils node class. This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents. Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers - can be given as keyword arguments: the keyword must be one or more of - ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``, the value a - 2-tuple of ``(visit, depart)`` methods. ``depart`` can be ``None`` if the - ``visit`` function raises :exc:`docutils.nodes.SkipNode`. Example: + can be given as keyword arguments: the keyword should be one or more of + ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'`` or any other + supported translators, the value a 2-tuple of ``(visit, depart)`` methods. + ``depart`` can be ``None`` if the ``visit`` function raises + :exc:`docutils.nodes.SkipNode`. Example: .. code-block:: python @@ -131,8 +146,8 @@ package. The directive class must inherit from the class ``docutils.parsers.rst.Directive``. - For example, the (already existing) :rst:dir:`literalinclude` directive would be - added like this: + For example, the (already existing) :rst:dir:`literalinclude` directive would + be added like this: .. code-block:: python @@ -212,10 +227,13 @@ package. .. index:: pair: function; directive The reference node will be of class ``literal`` (so it will be rendered in a - proportional font, as appropriate for code) unless you give the *ref_nodeclass* - argument, which must be a docutils node class (most useful are - ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use - ``docutils.nodes.generated`` if you want no further text decoration). + proportional font, as appropriate for code) unless you give the + *ref_nodeclass* argument, which must be a docutils node class. Most useful + are ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also + use ``docutils.nodes.generated`` if you want no further text decoration. If + the text should be treated as literal (e.g. no smart quote replacement), but + not have typewriter styling, use ``sphinx.addnodes.literal_emphasis`` or + ``sphinx.addnodes.literal_strong``. For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see :ref:`xref-syntax`). @@ -229,8 +247,8 @@ package. directive it generates must be empty, and will produce no output. That means that you can add semantic targets to your sources, and refer to - them using custom roles instead of generic ones (like :rst:role:`ref`). Example - call:: + them using custom roles instead of generic ones (like :rst:role:`ref`). + Example call:: app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis) @@ -270,6 +288,18 @@ package. .. versionadded:: 1.0 +.. method:: Sphinx.add_latex_package(packagename, options=None) + + Add *packagename* to the list of packages that LaTeX source code will include. + If you provide *options*, it will be taken to `\usepackage` declaration. + + .. code-block:: python + + app.add_latex_package('mypackage') # => \usepackage{mypackage} + app.add_latex_package('mypackage', 'foo,bar') # => \usepackage[foo,bar]{mypackage} + + .. versionadded:: 1.3 + .. method:: Sphinx.add_lexer(alias, lexer) Use *lexer*, which must be an instance of a Pygments lexer class, to @@ -419,6 +449,19 @@ handlers to the events. Example: .. 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 @@ -462,6 +505,26 @@ handlers to the events. Example: 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 (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. + + For a sample of how to deal with this event, look at the standard + ``sphinx.ext.todo`` extension. The implementation is often similar to that + of :event:`env-purge-doc`, only that information is not removed, but added to + the main environment from the other environment. + + .. versionadded:: 1.3 + .. event:: env-updated (app, env) Emitted when the :meth:`update` method of the build environment has @@ -495,8 +558,14 @@ handlers to the events. Example: 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. + .. versionadded:: 0.4 + .. versionchanged:: 1.3 + The return value can now specify a template name. + .. event:: build-finished (app, exception) Emitted when a build has finished, before Sphinx exits, usually used for |