sphinx-autodoc2 icon indicating copy to clipboard operation
sphinx-autodoc2 copied to clipboard

Docstrings don't seem to create linked headings

Open reivilibre opened this issue 2 years ago • 0 comments

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)

image

(but note the headings within the docstring don't have the permalink, which appears on hover:)

image

reivilibre avatar Mar 14 '23 08:03 reivilibre