Being able to use markdown in docs (files, module docs, function/class docs)

[thorwhalen]

• What possibilities does sphinx offer for markdown?
• pros and cons (rst more functional, md easier to start with but what are we sacrificing?)?
• Try out https://www.sphinx-doc.org/en/master/usage/markdown.html
• integrate with CI (isee)

[sylvainbonnot]

Here are some thoughts on that:

• sphinx offers some support for markdown: https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html, allowing to use .md files instead of .rst files to generate the docs.
• even with myst-parser, sphinx cannot at the moment convert markdown written within the docstrings: see the github issue no md in docstring
• pros of md: easier syntax, more people can read and write it
• workaround to convert markdown written inside a docstring (I checked it worked with sphinx, did not check yet with epythet):
  • pip install commonmark
  • inside the conf.py file of the sphinx doc, include this snippet:

    import commonmark
  
    def docstring(app, what, name, obj, options, lines):
        md  = '\n'.join(lines)
        ast = commonmark.Parser().parse(md)
        rst = commonmark.ReStructuredTextRenderer().render(ast)
        lines.clear()
        lines += rst.splitlines()
  
    def setup(app):
        app.connect('autodoc-process-docstring', docstring)
  

[thorwhalen]

That could work. How/where do we integrate with epythet. See with @andeaseme .

[thorwhalen]

Can you include some reference about how there's no support for md-parsing module's and function's docstrings in sphinx? Seems like if they can do it with files, docstrings shouldn't be too far away.

[sylvainbonnot]

The fact that sphinx, even with the myst-parser extension cannot do autodoc on functions docstrings without a hack is documented in that issue : no md docstring.

[sylvainbonnot]

This has been integrated in my fork of epythet: https://github.com/sylvainbonnot/epythet/blob/dev-sylvain/epythet/_static/docsrc/conf.py

In short: markdown within docstrings can be read by epythet.

Here is an example with a code block within docstrings: