sphinx-autodoc2
sphinx-autodoc2 copied to clipboard
Docstrings don't seem to create linked headings
I am entirely new to Sphinx so this could just be a PEBKAC, but I've not managed to find a solution after quite a bit of searching.
When documenting a module's docstring with Sphinx-Autodoc2, it doesn't generate headings that have a little # link (that would usually link to page.html#heading-name so you can link to a section of the documentation) and they don't appear in the 'Contents' sidebar in 2 of the themes I tried that had such a sidebar.
I'm using this Sphinx configuration:
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'autodoc2',
'myst_parser',
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for Autodoc2 ----------------------------------------------------
autodoc2_docstring_parser_regexes = [
# this will render all docstrings as 'MyST' Markdown
(r".*", "myst"),
]
autodoc2_packages = [
{
"path": "../mypackage",
# Don't render documentation for everything as a matter of course
"auto_mode": False,
},
]
# -- Options for MyST (Markdown) ---------------------------------------------
# tried with and without
#myst_heading_anchors = 2
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'furo'
html_static_path = ['_static']
Notably I am using MyST.
Here is a markdown file in which I am invoking autodoc2:
Page Title
==========
```{autodoc2-docstring} mypackage.mymodule
```
## A
## B
### C
## D
### E
(The content of mypackage.mymodule starts with a docstring containing headers of various depths)
(but note the headings within the docstring don't have the permalink, which appears on hover:)