I don't think it is possible to do this by returning the section from the directive (without doing something along the lines of what Florian suggested), as it will get appended to the 'current' section. You can, however, add the section via self.state.section as I do in the following (handling of options removed for brevity)
class FauxHeading(object):
""
"
A heading level that is not defined by a string.We need this to work with
the mechanics of
: py: meth: `docutils.parsers.rst.states.RSTState.check_subsection`.
The important thing is that the length can vary, but it must be equal to
any other instance of FauxHeading.
""
"
def __init__(self, length):
self.length = length
def __len__(self):
return self.length
def __eq__(self, other):
return isinstance(other, FauxHeading)
class ParmDirective(Directive):
required_arguments = 1
optional_arguments = 0
has_content = True
option_spec = {
'type': directives.unchanged,
'precision': directives.nonnegative_int,
'scale': directives.nonnegative_int,
'length': directives.nonnegative_int
}
def run(self):
variableName = self.arguments[0]
lineno = self.state_machine.abs_line_number()
secBody = None
block_length = 0
# added
for some space
lineBlock = nodes.line('', '', nodes.line_block())
# parse the body of the directive
if self.has_content and len(self.content):
secBody = nodes.container()
block_length += nested_parse_with_titles(
self.state, self.content, secBody)
# keeping track of the level seems to be required
if we want to allow
# nested content.Not sure why, but fits with the pattern in
#: py: meth: `docutils.parsers.rst.states.RSTState.new_subsection`
myLevel = self.state.memo.section_level
self.state.section(
variableName,
'',
FauxHeading(2 + len(self.options) + block_length),
lineno,
[lineBlock]
if secBody is None
else [lineBlock, secBody])
self.state.memo.section_level = myLevel
return []As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.,Many sections include a list of references to module documentation or external documents. These lists are created using the seealso directive.,Deprecated since version 1.1: This presentation-only directive is a legacy from older versions. Use a rst-class directive instead and add an appropriate style.,This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.
..toctree:: : maxdepth: 2 intro strings datatypes numeric (many more documents listed here)
.. toctree::
intro
All about strings <strings>
datatypes..toctree:: : numbered: foo bar
..toctree:: : caption: Table of Contents: name: mastertoc foo
..toctree:: : titlesonly: foo bar
..toctree:: : glob: intro * recipe /* *
This method must process the directive arguments, options and content, and return a list of Docutils/Sphinx nodes that will be inserted into the document tree at the point where the directive was encountered.,You can now create the files you listed in the toctree and add content, and their section titles will be inserted (up to the maxdepth level) at the place where the toctree directive is placed. Also, Sphinx now knows about the order and hierarchy of your documents. (They may contain toctree directives themselves, which means you can create deeply nested hierarchies if necessary.),Python code that is treated like it were put in a testsetup directive for every file that is tested, and for every group. You can use this to e.g. import modules you will always need in your doctests.,The directive content follows after a blank line and is indented relative to the directive start or if options are present, by the same amount as the options.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, run:
$ sphinx - quickstart
The toctree directive initially is empty, and looks like so:
..toctree:: : maxdepth: 2
You add documents listing them in the content of the directive:
..toctree:: : maxdepth: 2 usage / installation usage / quickstart ...
Now that you have added some files and content, let’s make a first build of the docs. A build is started with the sphinx-build program:
$ sphinx - build - b html sourcedir builddir
However, sphinx-quickstart script creates a Makefile and a make.bat which make life even easier for you. These can be executed by running make with the name of the builder. For example.
$ make html
The most prominent domain is the Python domain. For example, to document Python’s built-in function enumerate(), you would add this to one of your source files.
..py: function::enumerate(sequence[, start = 0])
Return an iterator that yields tuples of an index and an item of the *
sequence * .(And so on.)The Python domain also happens to be the default domain, so you don’t need to prefix the markup with the domain name.
..function::enumerate(sequence[, start = 0])
...There are several more directives for documenting other types of Python objects, for example py:class or py:method. There is also a cross-referencing role for each of these object types. This markup will create a link to the documentation of enumerate().
The: py: func: `enumerate`
function can be used
for...In order to use autodoc, you need to activate it in conf.py by putting the string 'sphinx.ext.autodoc' into the list assigned to the extensions config value:
extensions = ['sphinx.ext.autodoc']Then, you have a few additional directives at your disposal. For example, to document the function io.open(), reading its signature and docstring from the source file, you’d write this:
..autofunction::io.open
You can also document whole classes or even modules automatically, using member options for the auto directives, like
..automodule::io: members:
For example, to link to io.open() in the Python library manual, you need to setup your intersphinx_mapping like:
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None)
}