Add processing of sphinx-like docstring specs to pdoc via preprocessor.
Project description
# pdoc_prep: Add sphinx-like function doc specs to pdoc #
Prepares Python files that use sphinx-like parameter and return specifications for input to the pdoc documentation tool (https://pypi.org/project/pdoc/).
## Motivation:
The pdoc HTML output does not recognize function/method parameter and return specifications in doc strings as special. So,
:param foo: controls whether bar is set to None
:type foo: int
:return True for success, else False
:rtype bool
will show up literally. If a module to be documentated is instead preprocessed using this script, then the pdoc documentation will look like this:
```
foo (int): controls whether bar is set to None
returns True for success, else False
return type: bool
```
The keywords, such as **returns**, and parameters, such as **foo (int)** will be bold faced.
**Note:** whether '**:**' is used to introduce a specification, or '**@**' is controlled from a command line option. See main section below.
## Usage
shell> pdoc_run.py --html-dir docs src/pdoc_prep/pdoc_prep.py
This command may be run from the project root, from within the evolving docs directory, or in the package directory. Obviously, the paths need to be adjusted accordingly.
## Notes
**Note 1**
You may see:
DeprecationWarning: the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses
import imp
This warning occurs in pdoc, which is not modified by this preprocessor. To suppress the warning, you can define an environment variable:
export PYTHONWARNINGS=ignore
in the shell where you are working.
**Note2:**
It would be more sensible to include this functionality in the pdoc HTML production code itself. Alas, not enough time.
Prepares Python files that use sphinx-like parameter and return specifications for input to the pdoc documentation tool (https://pypi.org/project/pdoc/).
## Motivation:
The pdoc HTML output does not recognize function/method parameter and return specifications in doc strings as special. So,
:param foo: controls whether bar is set to None
:type foo: int
:return True for success, else False
:rtype bool
will show up literally. If a module to be documentated is instead preprocessed using this script, then the pdoc documentation will look like this:
```
foo (int): controls whether bar is set to None
returns True for success, else False
return type: bool
```
The keywords, such as **returns**, and parameters, such as **foo (int)** will be bold faced.
**Note:** whether '**:**' is used to introduce a specification, or '**@**' is controlled from a command line option. See main section below.
## Usage
shell> pdoc_run.py --html-dir docs src/pdoc_prep/pdoc_prep.py
This command may be run from the project root, from within the evolving docs directory, or in the package directory. Obviously, the paths need to be adjusted accordingly.
## Notes
**Note 1**
You may see:
DeprecationWarning: the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses
import imp
This warning occurs in pdoc, which is not modified by this preprocessor. To suppress the warning, you can define an environment variable:
export PYTHONWARNINGS=ignore
in the shell where you are working.
**Note2:**
It would be more sensible to include this functionality in the pdoc HTML production code itself. Alas, not enough time.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pdoc_prep-0.0.2.tar.gz
(2.1 kB
view hashes)
Built Distribution
Close
Hashes for pdoc_prep-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | eb54f709e39a92015e53a9c8c49608f03e64033333bd8a2164b729080567e6c0 |
|
MD5 | 36d641f87665a750279bebe314137373 |
|
BLAKE2b-256 | a8762bf74c31c3004d2777b07ef10def88160133b687bd444437d3946c14ef57 |