pythonpython-sphinxread-the-docsautodoc

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


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.


Solution

  • 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:
     ```