diff options
Diffstat (limited to 'doc/extdev')
| -rw-r--r-- | doc/extdev/appapi.rst | 30 | ||||
| -rw-r--r-- | doc/extdev/envapi.rst | 6 | ||||
| -rw-r--r-- | doc/extdev/index.rst | 1 | ||||
| -rw-r--r-- | doc/extdev/markupapi.rst | 2 | ||||
| -rw-r--r-- | doc/extdev/parserapi.rst | 8 | ||||
| -rw-r--r-- | doc/extdev/tutorial.rst | 24 |
6 files changed, 56 insertions, 15 deletions
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index c2ee4cc86..b5cb33a33 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -125,6 +125,28 @@ package. .. versionchanged:: 0.5 Added the support for keyword arguments giving visit functions. +.. method:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds) + + Register a Docutils node class as a numfig target. Sphinx numbers the node + automatically. And then the users can refer it using :rst:role:`numref`. + + *figtype* is a type of enumerable nodes. Each figtypes have individual + numbering sequences. As a system figtypes, ``figure``, ``table`` and + ``code-block`` are defined. It is able to add custom nodes to these + default figtypes. It is also able to define new custom figtype if new + figtype is given. + + *title_getter* is a getter function to obtain the title of node. It takes + an instance of the enumerable node, and it must return its title as string. + The title is used to the default title of references for :rst:role:`ref`. + By default, Sphinx searches ``docutils.nodes.caption`` or + ``docutils.nodes.title`` from the node as a title. + + Other keyword arguments are used for node visitor functions. See the + :meth:`Sphinx.add_node` for details. + + .. versionadded:: 1.4 + .. method:: Sphinx.add_directive(name, func, content, arguments, **options) Sphinx.add_directive(name, directiveclass) @@ -155,7 +177,7 @@ package. add_directive('literalinclude', literalinclude_directive, content = 0, arguments = (1, 0, 0), linenos = directives.flag, - language = direcitves.unchanged, + language = directives.unchanged, encoding = directives.encoding) .. versionchanged:: 0.6 @@ -336,6 +358,12 @@ package. .. versionadded:: 1.1 +.. method:: Sphinx.add_source_parser(name, suffix, parser) + + Register a parser class for specified *suffix*. + + .. versionadded:: 1.4 + .. method:: Sphinx.require_sphinx(version) Compare *version* (which must be a ``major.minor`` version string, diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst index 84ad3e0d9..729725fc5 100644 --- a/doc/extdev/envapi.rst +++ b/doc/extdev/envapi.rst @@ -17,7 +17,11 @@ Build environment API .. attribute:: srcdir - Source directory (the directory containing ``conf.py``). + Source directory. + + .. attribute:: confdir + + Directory containing ``conf.py``. .. attribute:: doctreedir diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 5144c5f8b..b27db4b2d 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -52,4 +52,5 @@ APIs used for writing extensions builderapi markupapi domainapi + parserapi nodes diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst index 577a39e0d..99a1ae9fb 100644 --- a/doc/extdev/markupapi.rst +++ b/doc/extdev/markupapi.rst @@ -135,5 +135,5 @@ return ``node.children`` from the Directive. .. seealso:: - `Creating directives <http://docutils.sf.net/docs/howto/rst-directives.html>`_ + `Creating directives <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ HOWTO of the Docutils documentation diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst new file mode 100644 index 000000000..7008a15a8 --- /dev/null +++ b/doc/extdev/parserapi.rst @@ -0,0 +1,8 @@ +.. _parser-api: + +Parser API +========== + +.. module:: sphinx.parsers + +.. autoclass:: Parser diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst index 8241e109e..10a14fab7 100644 --- a/doc/extdev/tutorial.rst +++ b/doc/extdev/tutorial.rst @@ -4,11 +4,11 @@ Tutorial: Writing a simple extension ==================================== This section is intended as a walkthrough for the creation of custom extensions. -It covers the basics of writing and activating an extensions, as well as +It covers the basics of writing and activating an extension, as well as commonly used features of extensions. As an example, we will cover a "todo" extension that adds capabilities to -include todo entries in the documentation, and collecting these in a central +include todo entries in the documentation, and to collect these in a central place. (A similar "todo" extension is distributed with Sphinx.) @@ -20,7 +20,7 @@ extension. These are: **Application** The application object (usually called ``app``) is an instance of - :class:`.Sphinx`. It controls the most high-level functionality, such as the + :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 @@ -29,8 +29,8 @@ extension. These are: **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 - after each build. + 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 @@ -64,7 +64,7 @@ in which a Sphinx project is built: this works in several phases. **Phase 0: Initialization** - In this phase, almost nothing interesting for us happens. The source + 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. @@ -73,8 +73,8 @@ in which a Sphinx project is built: this works in several phases. 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 the docutils, and the corresponding code is executed. The - output of this phase is a *doctree* for each source files, that is a tree of + 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. @@ -149,7 +149,7 @@ The new elements are added in the extension's setup function. Let us create a new Python module called :file:`todo.py` and add the setup function:: def setup(app): - app.add_config_value('todo_include_todos', False, False) + app.add_config_value('todo_include_todos', False, 'html') app.add_node(todolist) app.add_node(todo, @@ -171,7 +171,7 @@ the individual calls do is the following: new *config value* ``todo_include_todos``, whose default value should be ``False`` (this also tells Sphinx that it is a boolean value). - If the third argument was ``True``, all documents would be re-read if the + If the third argument was ``'html'``, HTML documents would be full rebuild if the config value changed its value. This is needed for config values that influence reading (build phase 1). @@ -229,8 +229,8 @@ The Directive Classes A directive class is a class deriving usually from :class:`docutils.parsers.rst.Directive`. The directive interface is also covered in detail in the `docutils documentation`_; the important thing is that -the class has attributes that configure the allowed markup and a method ``run`` -that returns a list of nodes. +the class should have attributes that configure the allowed markup, +and a ``run`` method that returns a list of nodes. The ``todolist`` directive is quite simple:: |