Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docstrings don't seem to create linked headings #22

Open
reivilibre opened this issue Mar 14, 2023 · 0 comments
Open

Docstrings don't seem to create linked headings #22

reivilibre opened this issue Mar 14, 2023 · 0 comments

Comments

@reivilibre
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant