autodoc-object directive#

The autodoc-object directive can be used to render the documentation for a single Python object. It takes a single argument, the fully qualified name of the object that should be rendered.

Using the :literal: option, the pre-rendered content will be rendered as a literal block, and the :literal-lexer: option can be used to specify the lexer to use for syntax highlighting.

The directive can contain content, which is read as TOML and will override any of the global configuration options (without the autodoc2_ prefix).

Literal representation#

For example:

.. autodoc2-object:: autodoc2.sphinx.docstring._example
    :literal:
    :literal-lexer: restructuredtext

    render_plugin = "rst"
    no_index = true

creates:

.. py:function:: _example(a: int, b: str) -> None
   :canonical: autodoc2.sphinx.docstring._example
   :noindex:

   .. autodoc2-docstring:: autodoc2.sphinx.docstring._example
      :parser: myst

Rendered representation#

For example:

.. autodoc2-object:: autodoc2.sphinx.docstring._example

    render_plugin = "rst"
    no_index = true

creates:

autodoc2.sphinx.docstring._example(a: int, b: str) → None[source]

This is an example docstring, written in MyST.

It has a code fence:

a = "hallo"

and a table:

a

b

c

1

2

3

and, using the fieldlist extension, a field list:

Parameters:

  • a – the first parameter

  • b – the second parameter

Returns:

the return value

Rendered representation (signature only)#

Or without annotations and docstring:

.. autodoc2-object:: autodoc2.sphinx.docstring._example

    render_plugin = "rst"
    no_index = true
    annotations = false
    docstrings = false

creates:

autodoc2.sphinx.docstring._example(a, b)[source]