Package: npdoc-to-md
npdoc_to_mdThanks tofreesvg.orgfor the logo assetsAutomatic documentation tool using Markdown and Python docstrings written with thenumpydoc style.This librarydoes not generate a website! It convertstemplatestrings/files/folders written inMarkdown. The result of that can be used for instance forGitHub or Gitlab Wiki.The features (see below) are somewhat basic. If you need more advanced features you might want to look into my suggestions forother documentation tools.FeaturesEasy to use: just place a few placeholders in template files andconvert a file or a folder of templateswith asingle commandSupportsall sectionsof a docstring in numpydoc style +custom sections(they'll be read as Markdown)Flexiblelanguage highlightingforexample outputs(render a markdown table, python code, raw code etc.) on a per-example basis or a per-docstring basisRequirementsPython 3.7+ (besides dataclasses that can be backported withpip install dataclassesthere would be too many changes for 3.6 compatibility which is obsolete anyways)dependencies of this library (seerequirements.txtandInstallation section)Installationpip install npdoc_to_mdInstall thefire libraryfrom Google touse the CLI(recommended)pip install fireQuickstartFor more features (e.g. rendering a whole folder in a single command) and explanations on the placeholders (lines
surrounded by{{ }}), head over to thedocumentation.1. Make a template in Markdown.npmdis the recommended file extension for template files using this library but that's entirely up to you.Content of our example templateHome.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 templateFrom a terminal:$ npdoc-to-md render-file -source "Home.npmd" --destination "Home.md"From Python:fromnpdoc_to_mdimportrender_filerender_file(source='Home.npmd',destination='Home.md')3. Enjoy the result 🐍BeforeCreates 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 |Aftercreate_random_table(nb_rows: int = 5) -> 'pandas.DataFrame'Creates a random tableParametersnb_rowsHow many rows to generateExamplesfromnpdoc_to_md.testingimportTestFunctionsdf=TestFunctions.create_random_table()print(df.to_markdown(index=False))ABCD6714787712966954811355181515886448683610Testing# 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-modulesDevelopmentI develop the library inside ofJupyter Labusing thejupytextextension.I recommend using this extension for the best experience.
It will split code blocks within modules in notebook cells and will allowinteractive development.If you wish you can also use the providedconda environment(seeenvironment.ymlfile) inside of Jupyter Lab/Notebook
thanks tonb_conda_kernels.Other documentation toolsNote that all libraries belowproduce a website and not markdown fileslikenpdoc_to_mddoes. I also wrote some feedback after trying them fornpdoc_to_md(see theresearch folder). Obviously this is not an exhaustive list of documentation tools.mkdocstrings: this library seems to have a few problems with numpydoc style docstringspydoc-markdown: does not seem to support numpydoc style docstrings (see thisissue). 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.MotivationSphinxis 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 tohost a website for private librariesand then also having to protect it with alogin.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.