Package: npdoc2md
npdoc2mdA simple python utility for auto-converting numpy-style python docstrings to
markdown for use with mkdocs, an entire package at a time. It also includes a second utility,code2npdoc, which will attempt to generate docstring templates given code for an entire project.InstallationThe preferred method for installing npdoc2md is to usepip. (Python 3.5+ required)pip install npdoc2mdIfpipdefaults to Python2, usepip3. You can also install from source:git clone https://github.com/jwlodek/npdoc2md
cd npdoc2md
pip install .UsageBelow is the result of runningnpdoc2mdwith the-hflag:usage: npdoc2md [-h] [-v] -i INPUT -o OUTPUT [-s SKIP [SKIP ...]] [-d]

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Use this flag to print out npdoc2md version info.
  -i INPUT, --input INPUT
                        The path to the target python project or file to
                        convert.
  -o OUTPUT, --output OUTPUT
                        The output directory where the markdown files should
                        be placed.
  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                        List of filenames/directories to skip.
  -d, --debug           Add this flag to print detailed log messages during
                        conversion.Basic usage will require at least target and output locations that are valid.npdoc2md -i C:\Users\jwlodek\demo -o C:\Users\jwlodek\demo_outputYou can also specify to enable debug printing with-d, and files to skip with-sfollowed by a list of files. For example, to autogeneratepy_cuidocs, the following command is run:npdoc2md -i ..\..\..\py_cui -o ..\..\DocstringGenerated -s statusbar.py errors.pywhich will ignore thestatusbar.pyanderrors.pyfiles.Thenpdoc2mdscript will recursively search the target (if it is a folder) for files ending with the.pyextension,
and will generate a markdown file for each one not specified in the ignore section. Any encountered__init__.pyfiles will use their containing folder's name for the name of the output markdown file.Doc RulesYou must follow strict docstring style rules to use npdoc2md:Each class of function docstring must start and end with""", and the initial description must be right after the initial""". Ex:"""Hello this is a functionUse numpy style guidelines forAttributes,Parameters,Returns,RaiseslistsTheReturnslist should give a return value name and type with the doc message. If it doesn't, a generic name will be assigned to the return variableExamplesAs stated previously,py_cuiuses npdoc2md to auto-generate documentation to use withmkdocs.
You may also see theNpdoc2md.mdfile in this repository which was generated by running this script on itself:npdoc2md -i .\npdoc2md.py -o .\example\.Generating template docsWriting out all of the docstrings for a project is a lengthy process, so a second helper script was written to help with generating template np docs. It has the following usage:usage: code2npdoc [-h] [-v] -i INPUT [-c] [-s SKIP [SKIP ...]] [-d]

A utility for auto-creating base numpy style docstrings for an entire python
project.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         Add this flag for displaying version information.
  -i INPUT, --input INPUT
                        Path to target python project or file
  -c, --createtemp      If this flag is set, code2npdoc will create a
                        temporary conversion folder without overriding your
                        sources.
  -s SKIP [SKIP ...], --skip SKIP [SKIP ...]
                        List of filenames/directories to skip.
  -d, --debug           Add this flag to print detailed log messages during
                        conversion.With similar flags as the basenpdoc2mdscript. Add the-cflag if you don't want your original file to be auto-overwritten. An example of running this script on thenpdoc2mdfile is as follows:code2npdoc -i npdoc2md.py -cLicenseMIT LicenseCopyright (c) 2020, Jakub Wlodek