How can I use automodule or autoclass for Sphinx in a markdown file?

Question

I understand the Sphinx supports markdown or .md files optionally, which works great for me for my supplimental documentation. What I am trying to do is use the autoclass or automodule tags in a markdown file.

Normally, in a .rst file, if I do

.. autoclass:: my.module.SomeClass
    :members:

it will automatically pull all the docstrings and create the documentation. Is it possible to use this in .md files? At the moment, when I attempt to do so, the generated docs only contains .. autoclass:... which is expected.

My conf.py is

extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "recommonmark"]
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

Because of read the docs compatibility, I did consider mkdocs, but it does not offer autodoc like capabilities. I am very open to any other library (does not have to be RTD compatible) in order to accomplish this.

Fathead

Answer 1

Use MyST

pip install myst-parser

Add this extension to your sphinx config:

extensions = [..., "myst_parser"]

Use {eval-rst} with autoclass role, within a ``` block

```{eval-rst}  
.. autoclass:: my.module.SomeClass
:members:
```

Old, deprecated way

This might require using AutoStructify of Recommonmark, namely the RST embedding feature.

With it, you'd add the following to your markdown:

 ```eval_rst
 .. autoclass:: my.module.SomeClass
 :members:
 ```

Floria

Answer 2

Adding the ".md" to the source_suffix list worked for me:

In your conf.py:

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = ['.rst', '.md']

I am using sphinx 2.1.2

Bennettbenni

Answer 3

If you're using MyST:

extensions = [
    'myst_parser',
    ...
]

All you need to do is:

```{eval_rst}
 .. autoclass:: my.module.SomeClass
 :members:
```

Repulsive

Note: this still works in 2024. Thanks! – Thermoplastic