restructuredText docstrings to .md files

Question

I have a Python project where i used restructuredText to comment/documentate each of my classes/functions. Here's a sample of my docstring :

"""
Updates the contacts birth date in batch
:param nb_contacts: nb_contacts: number of contacts to update
:param batch_size: size of the batch
:param context: airflow context
:return: true if update is successful
"""

I wanna generate .md files from my code. Is there anyway to do it ?

Just looking for something that can be well displayed on git and a human readable .md doc files. A doc that has the same structure as the .html documentation generated with sphinx but in .md files — Fragan, Jan 07 '21 at 08:49
Please note that comments and docstrings are two different things. What you have in the question is a docstring. — mzjn, Jan 07 '21 at 08:58

kluvin · Accepted Answer · 2021-01-07T08:57:37.880

1

Sphinx is probably what you are looking for, additionally it is possible to publish the generated documentation to ReadTheDocs, which you are probably familiar with already.

Any .rst files can strictly be converted to .md (or any other format) with pandoc, where you would do something like:

pandoc -f page.rst -t page.md

edited Jan 07 '21 at 08:57

answered Jan 07 '21 at 08:53

kluvin

5,235
3
13
20

But Sphinx only generates .rst files no ? Can we use convert those .rst files to markdown ? – Fragan Jan 07 '21 at 08:54
@Arès Updated my answer. – kluvin Jan 07 '21 at 08:57

score 1 · Answer 2 · answered Jan 07 '21 at 08:55

1

Generating Markdown from reStructuredText appears to be an uncommon combination. You'll find a question similar to yours on Markdown output for Sphinx based documentation

answered Jan 07 '21 at 08:55

Thomas Stenhaug

109
4

restructuredText docstrings to .md files

2 Answers2