Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jwlodek/npdoc2md
A script for auto-converting numpy-style documentation to markdown for an entire python project
https://github.com/jwlodek/npdoc2md
converter docs docstring-documentation docstrings markdown numpy script
Last synced: 3 months ago
JSON representation
A script for auto-converting numpy-style documentation to markdown for an entire python project
- Host: GitHub
- URL: https://github.com/jwlodek/npdoc2md
- Owner: jwlodek
- License: mit
- Created: 2020-02-06T20:57:21.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-02T12:32:29.000Z (over 3 years ago)
- Last Synced: 2024-09-28T09:21:48.760Z (3 months ago)
- Topics: converter, docs, docstring-documentation, docstrings, markdown, numpy, script
- Language: Python
- Size: 101 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/jwlodek/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`, `Raises` lists
* The `Returns` list 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](https://github.com/jwlodek/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