npdoc2md
A 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.
Installation
The preferred method for installing npdoc2md is to use pip. (Python 3.5+ required)
pip install npdoc2md
If pip defaults to Python2, use pip3. You can also install from source:
git clone https://github.com/jwlodek/npdoc2md
cd npdoc2md
pip install .
Usage
Below is the result of running npdoc2md with the -h flag:
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_output
You can also specify to enable debug printing with -d, and files to skip with -s followed by a list of files. For example, to autogenerate py_cui docs, the following command is run:
npdoc2md -i ..\..\..\py_cui -o ..\..\DocstringGenerated -s statusbar.py errors.py
which will ignore the statusbar.py and errors.py files.
The npdoc2md script will recursively search the target (if it is a folder) for files ending with the .py extension,
and will generate a markdown file for each one not specified in the ignore section. Any encountered __init__.py files will use their containing folder's name for the name of the output markdown file.
Doc Rules
You 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 function - Use numpy style guidelines for
Attributes,Parameters,Returns,Raiseslists - The
Returnslist 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 variable
Examples
As stated previously, py_cui uses npdoc2md to auto-generate documentation to use with mkdocs.
You may also see the Npdoc2md.md file in this repository which was generated by running this script on itself:
npdoc2md -i .\npdoc2md.py -o .\example\.
Generating template docs
Writing 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 base npdoc2md script. Add the -c flag if you don't want your original file to be auto-overwritten. An example of running this script on the npdoc2md file is as follows:
code2npdoc -i npdoc2md.py -c
License
MIT License
Copyright (c) 2020, Jakub Wlodek
Metadata
Release files for npdoc2md 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| npdoc2md-0.0.1.tar.gz | 10.8 kB | Without provenance | Details for npdoc2md-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| npdoc2md-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for npdoc2md-0.0.1-py3-none-any.whl |
Total release size: 23.6 kB
Release files / npdoc2md-0.0.1.tar.gz
| Download URL | npdoc2md-0.0.1.tar.gz |
|---|---|
| Size | 10.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2fc9d872dbdfc9b743da38859a8e43ad730e62d01e1affa361dbdb3862056eb9
|
|
BLAKE2b-256 checksum How to use checksums |
1e8bdd39d2f050a6dfb2a54dc4ca054601829a9abe5e639cae85c9d5cb0f3422
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.7.0
|
Release files / npdoc2md-0.0.1-py3-none-any.whl
| Download URL | npdoc2md-0.0.1-py3-none-any.whl |
|---|---|
| Size | 12.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c644e0964def0053acc1b6895e919ff051e11522bcbe9337d03a7b364ed38bd
|
|
BLAKE2b-256 checksum How to use checksums |
941e45b5d560ece761b071769d24aad6f80d77c743390c41e5bce4e3a263d7b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.7.0
|
Security for npdoc2md 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.