This piece of code can be used to convert NumPy-styled Python docstrings (example), such as those used in scikit-learn, to Markdown with minimum dependencies. In this way, only the code-contained documentation needs to be editted, and your documentation on for example readthedocs can be automatically updated thereafter with some configuration.
The converted documentation for this particular code can be found here.
The format assumes that your code (or at least your docstring documentation) is in line with the styleguides of both PEP8 and PEP257. There are two ways to go about making sure this is the case:
Just check the example here to get a quick overview of how the docstrings would have to look in order for them to parse correctly.
The styleguides are incorporated into two libraries that can be used to check the Python files for style errors in terminal, like so:
pip install pep8 pip install pep257 pep8 yourpythonfile.py pep257 yourpythonfile.py
First clone from GitHub:
git clone https://www.github.com/cmry/markdoc
To use the script within terminal, simply type:
python3 markdoc.py /dir/to/somefile.py /dir/to/somedoc.md
If you want to automatically generate a bunch of documentation and are not
comfortable with writing
.sh scripts, you can use the code in Python as well:
from markdoc import MarkDoc md = MarkDoc('/dir/to/somefile.py', '/dir/to/somedoc.md')
You can access the converted markdown string in:
# print markdown from class attribute print(md.markdown)
The class runs itself on initialization (calls
self.read). If you do not
want this, you can add
cold=True to the class initialization, like so:
md = MarkDoc('file.py', 'doc.md', cold=True)
- Handle consecutive classes within the same file.
- Fix inherrited classes being handled correctly (no
- Link class methods from table to their documentation.
- Might not handle decorators neatly.
- Do not use
"""for anything other than docstrings.
- First line of any docstring has to contain the first short title (example).
- Classes have to be structured new-style:
- Codeblocks in examples have to be vanilla Python (
- Please do not use
classas a parameter name!
Script has only been tested with Python 3.4 on Ubuntu.