Easy conversion of Python docstrings in numpy style to markdown! Includes a Markdown renderer.
Project description
npdoc_to_md
Turns numpy docstrings to pretty markdown.
Table of contents
Features
- Very easy to use
- Flexible rendering for example outputs (render a markdown table, python code, raw code etc.) on a per-example basis or a per-docstring basis
- Provides file rendering with very simple placeholders
Caveats
- GitHub does not support colors for markdown 😿
Installation
pip install npdoc_to_md
Demos
First demo: Demonstration with the docstring of pandas.Series.
Before
Two-dimensional, size-mutable, potentially heterogeneous tabular data.
Data structure also contains labeled axes (rows and columns).
Arithmetic operations align on both row and column labels. Can be
thought of as a dict-like container for Series objects. The primary
pandas data structure.
Parameters
----------
data : ndarray (structured or homogeneous), Iterable, dict, or DataFrame
Dict can contain Series, arrays, constants, or list-like objects.
.. versionchanged:: 0.23.0
If data is a dict, column order follows insertion-order for
Python 3.6 and later.
.. versionchanged:: 0.25.0
If data is a list of dicts, column order follows insertion-order
for Python 3.6 and later.
index : Index or array-like
Index to use for resulting frame. Will default to RangeIndex if
no indexing information part of input data and no index provided.
columns : Index or array-like
Column labels to use for resulting frame. Will default to
RangeIndex (0, 1, 2, ..., n) if no column labels are provided.
dtype : dtype, default None
Data type to force. Only a single dtype is allowed. If None, infer.
copy : bool, default False
Copy data from inputs. Only affects DataFrame / 2d ndarray input.
See Also
--------
DataFrame.from_records : Constructor from tuples, also record arrays.
DataFrame.from_dict : From dicts of Series, arrays, or dicts.
read_csv
read_table
read_clipboard
Examples
--------
Constructing DataFrame from a dictionary.
>>> d = {'col1': [1, 2], 'col2': [3, 4]}
>>> df = pd.DataFrame(data=d)
>>> df
col1 col2
0 1 3
1 2 4
Notice that the inferred dtype is int64.
>>> df.dtypes
col1 int64
col2 int64
dtype: object
To enforce a single dtype:
>>> df = pd.DataFrame(data=d, dtype=np.int8)
>>> df.dtypes
col1 int8
col2 int8
dtype: object
Constructing DataFrame from numpy ndarray:
>>> df2 = pd.DataFrame(np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]),
... columns=['a', 'b', 'c'])
>>> df2
a b c
0 1 2 3
1 4 5 6
2 7 8 9
After
pd.DataFrame(data=None, index: Union[Collection, NoneType] = None, columns: Union[Collection, NoneType] = None, dtype: Union[ForwardRef('ExtensionDtype'), str, numpy.dtype, Type[Union[str, float, int, complex, bool]], NoneType] = None, copy: bool = False)
Two-dimensional, size-mutable, potentially heterogeneous tabular data.
Data structure also contains labeled axes (rows and columns). Arithmetic operations align on both row and column labels. Can be thought of as a dict-like container for Series objects. The primary pandas data structure.
Parameters
-
data : ndarray (structured or homogeneous), Iterable, dict, or DataFrame Dict can contain Series, arrays, constants, or list-like objects.
.. versionchanged:: 0.23.0 If data is a dict, column order follows insertion-order for Python 3.6 and later.
.. versionchanged:: 0.25.0 If data is a list of dicts, column order follows insertion-order for Python 3.6 and later.
-
index : Index or array-like Index to use for resulting frame. Will default to RangeIndex if no indexing information part of input data and no index provided.
-
columns : Index or array-like Column labels to use for resulting frame. Will default to RangeIndex (0, 1, 2, ..., n) if no column labels are provided.
-
dtype : dtype, default None Data type to force. Only a single dtype is allowed. If None, infer.
-
copy : bool, default False Copy data from inputs. Only affects DataFrame / 2d ndarray input.
See Also
- DataFrame.from_records : Constructor from tuples, also record arrays.
- DataFrame.from_dict : From dicts of Series, arrays, or dicts.
- read_csv : Read a comma-separated values (csv) file into DataFrame.
- read_table : Read general delimited file into DataFrame.
- read_clipboard : Read text from clipboard into DataFrame.
Examples
Constructing DataFrame from a dictionary.
d = {'col1': [1, 2], 'col2': [3, 4]}
df = pd.DataFrame(data=d)
df
col1 col2
0 1 3
1 2 4
Notice that the inferred dtype is int64.
df.dtypes
col1 int64
col2 int64
dtype: object
To enforce a single dtype:
df = pd.DataFrame(data=d, dtype=np.int8)
df.dtypes
col1 int8
col2 int8
dtype: object
Constructing DataFrame from numpy ndarray:
df2 = pd.DataFrame(np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]),
columns=['a', 'b', 'c'])
df2
a b c
0 1 2 3
1 4 5 6
2 7 8 9
Second demo: the library pangres (also from me) which uses markdown tables in examples!
See https://github.com/ThibTrip/pangres/wiki/Upsert#examples
Usage
Head over to npdoc_to_md's wiki!
Contributing
Pull requests/issues are welcome.
Generating the documentation
All the documentation (this README and the wiki) needs to be generated from files contained in ./npdoc_to_md/docs
.
This is easy to do with the included script ./npdoc_to_md/docs/generate_documentation.py
:
- Clone the repo if you have not already (
https://github.com/ThibTrip/npdoc_to_md.git
) - Clone the wiki (
git clone https://github.com/ThibTrip/npdoc_to_md.wiki.git
) - Execute the commands below in your terminal (while located in the root folder of npdoc_to_md that you have cloned on your computer). Replace
NPDOC_TO_MD_PATH
with the path where you cloned npdoc_to_md's repo and replaceWIKI_FOLDER_PATH
with the path to where you cloned the wiki. Note: don't mind the errors with the line "{{raw}}" and "{{python}}" for the file "Home.md" (since npdoc_to_md is rendering its own documentation things get a little weird).
cd ./npdoc_to_md/docs
python generate_documentation.py NPDOC_TO_MD_PATH WIKI_FOLDER_PATH
- Commit the changes in the wiki
IMPORTANT: Do not modify the wiki or the README directly! Modify the files in ./npdoc_to_md/docs
instead.
Testing
Clone npdoc_to_md then set your curent working directory to the root of the cloned repository folder. Then use the commands below:
# 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
# -s prints stdout
# -v prints test parameters
# --cov=./npdoc_to_md shows coverage only for npdoc_to_md
pytest -s -vv npdoc_to_md --cov=./npdoc_to_md --doctest-modules
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
Built Distribution
Hashes for npdoc_to_md-1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0852cc42d2aa10f83bc9f2aacc7cee5ac03072fc976de127c15dd260ebf3fb71 |
|
MD5 | 0598d2411b00a726d1086c0393c4eba2 |
|
BLAKE2b-256 | fba105f438ffa548a812890b80f1ce94900f371bdd7970275d8bda99289d108d |