npdoc_to_md

Thanks to freesvg.org for the logo assets

Automatic documentation tool using Markdown and Python docstrings written with the numpydoc style.

This library does not generate a website! It converts template strings/files/folders written in Markdown. The result of that can be used for instance for GitHub or Gitlab Wiki.

The features (see below) are somewhat basic. If you need more advanced features you might want to look into my suggestions for other documentation tools.

Features

• Easy to use: just place a few placeholders in template files and convert a file or a folder of templates with a single command
• Supports all sections of a docstring in numpydoc style + custom sections (they'll be read as Markdown)
• Flexible language highlighting for example outputs (render a markdown table, python code, raw code etc.) on a per-example basis or a per-docstring basis

Requirements

• Python 3.7+ (besides dataclasses that can be backported with pip install dataclasses there would be too many changes for 3.6 compatibility which is obsolete anyways)
• dependencies of this library (see requirements.txt and Installation section)

Installation

pip install npdoc_to_md

Install the fire library from Google to use the CLI (recommended)

pip install fire

Quickstart

For more features (e.g. rendering a whole folder in a single command) and explanations on the placeholders (lines surrounded by {{ }}), head over to the documentation.

1. Make a template in Markdown

.npmd is the recommended file extension for template files using this library but that's entirely up to you.

Content of our example template Home.npmd:

# My super cool library

## Some dummy function

{{"obj":"npdoc_to_md.testing.create_random_table", "alias":"create_random_table", "examples_md_lang":"markdown_rendered", "remove_doctest_skip":true, "remove_doctest_blanklines":true, "md_section_level":3}}

2. Render the template

From a terminal:

$ npdoc-to-md render-file -source "Home.npmd" --destination "Home.md"

From Python:

from npdoc_to_md import render_file

render_file(source='Home.npmd', destination='Home.md')

3. Enjoy the result 🐍

Before

Creates a random table

Parameters
----------
nb_rows
    How many rows to generate

Examples
--------
>>> from npdoc_to_md.testing import TestFunctions
>>>
>>> df = TestFunctions.create_random_table()
>>> print(df.to_markdown(index=False))  # doctest: +SKIP
|   A |   B |   C |   D |
|----:|----:|----:|----:|
|  67 |  14 |  78 |  77 |
|  12 |  96 |  69 |  54 |
|  81 |  13 |  55 |  18 |
|  15 |  15 |  88 |  64 |
|  48 |  68 |  36 |  10 |

After

create_random_table(nb_rows: int = 5) -> 'pandas.DataFrame'

Creates a random table

Parameters

• nb_rows

  How many rows to generate

Examples

from npdoc_to_md.testing import TestFunctions

df = TestFunctions.create_random_table()
print(df.to_markdown(index=False))

Testing

# 1. Create and activate the build environment
conda env create -f environment.yml
conda activate npdoc_to_md-dev
# 2. Install npdoc_to_md in editable mode (changes are reflected upon reimporting)
pip install -e .
# 3. Run pytest
pytest -sv npdoc_to_md --cov=npdoc_to_md --doctest-modules

Development

I develop the library inside of Jupyter Lab using the jupytext extension.

I recommend using this extension for the best experience. It will split code blocks within modules in notebook cells and will allow interactive development.

If you wish you can also use the provided conda environment (see environment.yml file) inside of Jupyter Lab/Notebook thanks to nb_conda_kernels.

Other documentation tools

Note that all libraries below produce a website and not markdown files like npdoc_to_md does. I also wrote some feedback after trying them for npdoc_to_md (see the research folder). Obviously this is not an exhaustive list of documentation tools.

• mkdocstrings: this library seems to have a few problems with numpydoc style docstrings
• pydoc-markdown: does not seem to support numpydoc style docstrings (see this issue). I have not gotten it to work yet because I have an error with the most basic configuration (no next element for the walker to move to)
• sphinx: sphinx works quite well with the simple example I provided. I didn't manage to get markdown inside docstrings to work though.

Motivation

Sphinx is what motivated me to make such a library several years ago (it was first private for a long time).

I was never 100% satisfied with the results (I had much more complex cases including the presence of subpackages) despite a lot of time spent tweaking sphinx. I also did not like the idea of having to host a website for private libraries and then also having to protect it with a login.

There is probably a library I could use as backend instead of doing a big part of the parsing myself or maybe even a library that could replace this one. Feel free to contact me if you come up with something interesting. This was a great learning project though and I am very happy with the current results.