From 0ab08db57feecf998a0f88c31cdac1a39495ddab Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Jul 2009 12:28:45 +0200 Subject: Fix long lines. --- doc/ext/autosummary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ext') diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 57abd616..f270a67b 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -220,6 +220,6 @@ The following variables available in the templates: for classes. .. note:: - + You can use the :dir:`autosummary` directive in the stub pages. Stub pages are generated also based on these directives. -- cgit v1.2.1 From d042abf5a65bf720d7b16488453b57b97ddc8cef Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 26 Jul 2009 15:00:18 +0200 Subject: Builder.load_env is no more. --- doc/ext/builderapi.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'doc/ext') diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst index bb11bfe2..3ace2687 100644 --- a/doc/ext/builderapi.rst +++ b/doc/ext/builderapi.rst @@ -13,7 +13,6 @@ Writing new builders These methods are predefined and will be called from the application: - .. automethod:: load_env .. automethod:: get_relative_uri .. automethod:: build_all .. automethod:: build_specific -- cgit v1.2.1 From 4d587fdf718a171359198d412f5a1d6e995b7ed7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 7 Sep 2009 22:52:26 +0200 Subject: More refactoring for language-independent domain support. * Renamed "desc"ription unit to "object" wherever possible. * Added standard x-ref types to a StandardDomain which is always consulted. * Split domains module into a subpackage. * Removed additional_xref_types in favor of new directive classes in StandardDomain. * Implemented x-ref inventory version 2, for all object types. * Added env.doc_read_data which is for temporary data stored while reading. * Minimally updated extension tutorial. * Started to implement changes to interactive search. * Test suite passes again. --- doc/ext/tutorial.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst index c44748d2..43d12ccb 100644 --- a/doc/ext/tutorial.rst +++ b/doc/ext/tutorial.rst @@ -201,8 +201,7 @@ The ``todo`` directive function looks like this:: def run(self): env = self.state.document.settings.env - targetid = "todo-%s" % env.index_num - env.index_num += 1 + targetid = "todo-%s" % env.new_serialno('todo') targetnode = nodes.target('', '', ids=[targetid]) ad = make_admonition(todo, self.name, [_('Todo')], self.options, @@ -225,9 +224,10 @@ to the build environment instance using ``self.state.document.settings.env``. Then, to act as a link target (from the todolist), the todo directive needs to return a target node in addition to the todo node. The target ID (in HTML, this -will be the anchor name) is generated by using ``env.index_num`` which is -persistent between directive calls and therefore leads to unique target names. -The target node is instantiated without any text (the first two arguments). +will be the anchor name) is generated by using ``env.new_serialno`` which is +returns a new integer directive on each call and therefore leads to unique +target names. The target node is instantiated without any text (the first two +arguments). An admonition is created using a standard docutils function (wrapped in Sphinx for docutils cross-version compatibility). The first argument gives the node -- cgit v1.2.1 From fa67fd6b1423364839e0b48bed99bbfb55271653 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 19:58:40 +0100 Subject: Finish renaming description units to object (description)s. --- doc/ext/appapi.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 0a3dae8f..754f22eb 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -123,26 +123,28 @@ the following public API: .. versionadded:: 0.6 -.. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None) +.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='') - This method is a very convenient way to add a new type of information that + This method is a very convenient way to add a new :term:`object` type that can be cross-referenced. It will do this: - * Create a new directive (called *directivename*) for a :term:`description - unit`. It will automatically add index entries if *indextemplate* is - nonempty; if given, it must contain exactly one instance of ``%s``. See - the example below for how the template will be interpreted. + * Create a new directive (called *directivename*) for documenting an object. + It will automatically add index entries if *indextemplate* is nonempty; if + given, it must contain exactly one instance of ``%s``. See the example + below for how the template will be interpreted. * Create a new role (called *rolename*) to cross-reference to these - description units. + object descriptions. * If you provide *parse_node*, it must be a function that takes a string and a docutils node, and it must populate the node with children parsed from the string. It must then return the name of the item to be used in cross-referencing and index entries. See the :file:`ext.py` file in the source for this documentation for an example. + * The *objname* (if not given, will default to *directivename*) names the + type of object. It is used when listing objects, e.g. in search results. For example, if you have this call in a custom Sphinx extension:: - app.add_description_unit('directive', 'dir', 'pair: %s; directive') + app.add_object_type('directive', 'dir', 'pair: %s; directive') you can use this markup in your documents:: @@ -164,12 +166,15 @@ the following public API: ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use ``docutils.nodes.generated`` if you want no further text decoration). - For the role content, you have the same options as for standard Sphinx roles - (see :ref:`xref-syntax`). + For the role content, you have the same syntactical possibilities as for + standard Sphinx roles (see :ref:`xref-syntax`). -.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None) + This method is also available under the deprecated alias + :meth:`add_description_unit`. - This method is very similar to :meth:`add_description_unit` except that the +.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='') + + This method is very similar to :meth:`add_object_type` except that the 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 -- cgit v1.2.1 From 05706159492a57568e615486e3c6032de521ea01 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 13 Jan 2010 23:42:58 +0100 Subject: Add html-collect-pages event. --- doc/ext/appapi.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 7ed3d3d4..f3a4a061 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -360,7 +360,15 @@ registered event handlers. .. versionadded:: 0.5 -.. event:: page-context (app, pagename, templatename, context, doctree) +.. 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. -- cgit v1.2.1 From af1328ec3da2e64b226dd463c428046e1ab910e2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 13 Jan 2010 23:53:01 +0100 Subject: Add the "viewcode" extension. --- doc/ext/viewcode.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 doc/ext/viewcode.rst (limited to 'doc/ext') diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst new file mode 100644 index 00000000..ba6c8f86 --- /dev/null +++ b/doc/ext/viewcode.rst @@ -0,0 +1,19 @@ +:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code +================================================================== + +.. module:: sphinx.ext.viewcode + :synopsis: Add links to a highlighted version of the source code. +.. moduleauthor:: Georg Brandl + +.. versionadded:: 1.0 + + +This extension looks at your Python object descriptions (``.. class::``, +``.. function::`` etc.) and tries to find the source files where the objects are +contained. When found, a separate HTML page will be output for each module with +a highlighted version of the source code, and a link will be added to all object +descriptions that leads to the source code of the described object. A link back +from the source to the description will also be inserted. + +There are currently no configuration values for this extension; you just need to +add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to work. -- cgit v1.2.1 From 9589493115cdd7d2fd3efa5d19600441c9472cc1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 14 Jan 2010 11:18:28 +0100 Subject: Fix docs of emit_firstresult(). --- doc/ext/appapi.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index f3a4a061..77ced4ef 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -269,8 +269,7 @@ the following public API: .. method:: Sphinx.emit_firstresult(event, *arguments) Emit *event* and pass *arguments* to the callback functions. Return the - result of the first callback that doesn't return ``None`` (and don't call - the rest of the callbacks). + result of the first callback that doesn't return ``None``. .. versionadded:: 0.5 -- cgit v1.2.1 From 2936c97ec0ff8b2690b97a7f3e8cc59912d191b8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 14 Jan 2010 22:28:03 +0100 Subject: Document three new appapi functions. --- doc/ext/appapi.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 77ced4ef..12d004a1 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -43,6 +43,15 @@ the following public API: ``'env'``) to a string. However, booleans are still accepted and converted internally. +.. method:: Sphinx.add_domain(domain) + + Make the given *domain* (which must be a subclass of + :class:`sphinx.domains.Domain`) known to Sphinx. + + .. XXX where is Domain documented? + + .. versionadded:: 1.0 + .. method:: Sphinx.add_event(name) Register an event called *name*. @@ -81,10 +90,10 @@ the following public API: Register a Docutils directive. *name* must be the prospective directive name. There are two possible ways to write a directive: - * In the docutils 0.4 style, *func* is the directive function. *content*, + * In the docutils 0.4 style, *obj* is the directive function. *content*, *arguments* and *options* are set as attributes on the function and determine whether the directive has content, arguments and options, - respectively. + respectively. **This style is deprecated.** * In the docutils 0.5 style, *directiveclass* is the directive class. It must already have attributes named *has_content*, *required_arguments*, @@ -114,12 +123,26 @@ the following public API: .. versionchanged:: 0.6 Docutils 0.5-style directive classes are now supported. +.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options) + Sphinx.add_directive_to_domain(domain, name, directiveclass) + + Like :meth:`add_directive`, but the directive is added to the domain named + *domain*. + + .. versionadded:: 1.0 + .. method:: Sphinx.add_role(name, role) Register a Docutils role. *name* must be the role name that occurs in the source, *role* the role function (see the `Docutils documentation `_ on details). +.. method:: Sphinx.add_role_to_domain(domain, name, role) + + Like :meth:`add_role`, but the role is added to the domain named *domain*. + + .. versionadded:: 1.0 + .. method:: Sphinx.add_generic_role(name, nodeclass) Register a Docutils role that does nothing but wrap its contents in the -- cgit v1.2.1 From 7429ae935ec47c56c95998a8537236d4c1da7a2b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Feb 2010 11:50:08 +0100 Subject: Add manual page writer. --- doc/ext/appapi.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index a643a478..8df028e1 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -61,11 +61,11 @@ the following public API: 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 and text writers can be - given as keyword arguments: the keyword must be one or more of ``'html'``, - ``'latex'``, ``'text'``, the value a 2-tuple of ``(visit, depart)`` methods. - ``depart`` can be ``None`` if the ``visit`` function raises - :exc:`docutils.nodes.SkipNode`. Example: + 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'``, 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 -- cgit v1.2.1 From 42fc484adb89d951066b49143ce62c0264bca3f2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 27 Feb 2010 23:13:51 +0100 Subject: Add app.override_domain(). --- doc/ext/appapi.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 8df028e1..b536fd98 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -45,16 +45,24 @@ the following public API: .. method:: Sphinx.add_domain(domain) - Make the given *domain* (which must be a subclass of + Make the given *domain* (which must be a class; more precisely, a subclass of :class:`sphinx.domains.Domain`) known to Sphinx. .. XXX where is Domain documented? .. versionadded:: 1.0 +.. method:: Sphinx.override_domain(domain) + + Make the given *domain* known to Sphinx, assuming that there is already a + domain with its ``.name``. The new domain must be a subclass of the existing + one. + + .. versionadded:: 1.0 + .. method:: Sphinx.add_event(name) - Register an event called *name*. + Register an event called *name*. This is needed to be able to emit it. .. method:: Sphinx.add_node(node, **kwds) -- cgit v1.2.1 From ffe393b1b0a47d28c770668378ccff750fa82be3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 28 Feb 2010 11:39:13 +0100 Subject: #187: Added support for source ordering of members in autodoc, with ``autodoc_member_order = 'bysource'``. --- doc/ext/autodoc.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 4098d711..08a54082 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -223,10 +223,16 @@ There are also new config values that you can set: .. confval:: autodoc_member_order This value selects if automatically documented members are sorted - alphabetical (value ``'alphabetical'``) or by member type (value - ``'groupwise'``). The default is alphabetical. + alphabetical (value ``'alphabetical'``), by member type (value + ``'groupwise'``) or by source order (value ``'bysource'``). The default is + alphabetical. + + Note that for source order, the module must be a Python module with the + source code available. .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support for ``'bysource'``. .. confval:: autodoc_default_flags -- cgit v1.2.1 From 4d77d3d6fb8859f859ecd46a7aa3a03923b9cfa2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 28 Feb 2010 14:45:43 +0100 Subject: Change domain-index API: introduce a class. --- doc/ext/appapi.rst | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) (limited to 'doc/ext') diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index b536fd98..e301cd84 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -46,17 +46,22 @@ the following public API: .. method:: Sphinx.add_domain(domain) Make the given *domain* (which must be a class; more precisely, a subclass of - :class:`sphinx.domains.Domain`) known to Sphinx. - - .. XXX where is Domain documented? + :class:`~sphinx.domains.Domain`) known to Sphinx. .. versionadded:: 1.0 .. method:: Sphinx.override_domain(domain) - Make the given *domain* known to Sphinx, assuming that there is already a - domain with its ``.name``. The new domain must be a subclass of the existing - one. + Make the given *domain* class known to Sphinx, assuming that there is already + a domain with its ``.name``. The new domain must be a subclass of the + existing one. + + .. versionadded:: 1.0 + +.. method:: Sphinx.add_index_to_domain(domain, index) + + Add a custom *index* class to the domain named *domain*. *index* must be a + subclass of :class:`~sphinx.domains.Index`. .. versionadded:: 1.0 @@ -445,3 +450,19 @@ The template bridge .. autoclass:: TemplateBridge :members: + + +.. _domain-api: + +Domain API +---------- + +.. module:: sphinx.domains + +.. autoclass:: Domain + :members: + +.. autoclass:: ObjType + +.. autoclass:: Index + :members: -- cgit v1.2.1 From fc031d02297ccf1a6224fca0b0322236f310147d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 14 Mar 2010 19:46:54 +0100 Subject: A bit more tutorial. --- doc/ext/autodoc.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/ext') diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 08a54082..7e280b34 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -89,6 +89,9 @@ directive. .. autoclass:: Noodle :members: eat, slurp + * If you want to make the ``members`` option the default, see + :confval:`autodoc_default_flags`. + * Members without docstrings will be left out, unless you give the ``undoc-members`` flag option:: -- cgit v1.2.1