## mkgendocs
A Python package for automatically generating documentation pages in markdown for
Python source files by parsing **Google style docstring**. The markdown output makes it
ideal to combine with [mkdocs](https://www.mkdocs.org/).
Instead of executing the python code (using the `inspect` package to access signatures and docstrings), we extract the information directly from the source files by parsing them into Abstract Syntax Trees (AST) using the `ast` package.
The `astor` (AST observe/rewrite) package is also used to convert function or class signatures from AST nodes back into source code strings.
## Installation
Install mkgendocs from [PyPI](https://pypi.org/project/mkgendocs/)
```python
pip install mkgendocs
```
## Usage
```
gendocs --config mkgendocs.yml
```
A sources directory is created with the documentation that was automatically generated.
Any examples in a "examples" directory are automatically copied over to the documentation,
the module level docstrings of any example source files are also copied and converted to markdown.
### Configuration Example
````yaml
sources_dir: docs/sources
templates_dir: docs/templates
repo: https://github.com/davidenunes/tensorx #link to sources on github
version: master #link to sources on github
pages:
- page: "api/train/model.md"
source: "tensorx/train/model.py"
methods:
- Model:
- train
- set_optimizer
- page: "api/layers/core.md"
source: 'tensorx/layers.py'
classes:
- Linear:
- compute_shape
- Module
- page: "math.md"
source: 'tensorx/math.py'
functions:
- sparse_multiply_dense
# creates an index page based on everything from target source
- page: "api/layers/index.md"
source: "tensorx/layers.py"
index: True
````
* **sources_dir**: directory where the resulting markdown files are created
* **templates_dir**: directory where template files can be stored. All the folders and files are
copied to the `sources_dir`. Any markdown files are used as templates with the
tag `{{autogenerated}}` in the template files being replaced by the generated documentation.
* **repo**: repository to create `view source` links automatically for each class, function, and method;
* **version**: defaults to "master" to create link to sources in the form `https://repo/blob/version/file.py/#L1425`;
* **pages**: list of pages to be automatically generated from the respective source files and templates:
* **page**: path for page template / sources dir for the resulting page;
* **source**: path to source file from which the page is to be generated;
* **classes**: list of classes to be fully documented; a list of method names can be passed for each class, the default is
to generate all methods;
* **functions**: list of functions to be documented.
* **index**: if True creates an index page for the given sources, you can also specify classes and functions, but not methods
## Buy me a coffee
If you find any of this useful, consider getting me some coffee, coffee is great!
<br/><br/>
<a href='https://ko-fi.com/Y8Y0RZO6' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://az743702.vo.msecnd.net/cdn/kofi3.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
Raw data
{
"_id": null,
"home_page": "https://github.com/davidenunes/mkgendocs",
"name": "mkgendocs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "mkgendocs,docs,documentation,automation,mkdocs,cli",
"author": "Davide Nunes",
"author_email": "davidelnunes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fb/a0/9505f017d1fe5ca8cffb9849f49aebaa4255301d3bef517494d836608073/mkgendocs-0.9.2.tar.gz",
"platform": null,
"description": "## mkgendocs\nA Python package for automatically generating documentation pages in markdown for \nPython source files by parsing **Google style docstring**. The markdown output makes it\nideal to combine with [mkdocs](https://www.mkdocs.org/). \n\nInstead of executing the python code (using the `inspect` package to access signatures and docstrings), we extract the information directly from the source files by parsing them into Abstract Syntax Trees (AST) using the `ast` package. \n\nThe `astor` (AST observe/rewrite) package is also used to convert function or class signatures from AST nodes back into source code strings.\n \n\n\n## Installation\nInstall mkgendocs from [PyPI](https://pypi.org/project/mkgendocs/)\n\n```python\npip install mkgendocs\n```\n\n## Usage\n\n```\ngendocs --config mkgendocs.yml\n```\n\nA sources directory is created with the documentation that was automatically generated.\nAny examples in a \"examples\" directory are automatically copied over to the documentation, \nthe module level docstrings of any example source files are also copied and converted to markdown. \n\n\n### Configuration Example\n\n````yaml\nsources_dir: docs/sources\ntemplates_dir: docs/templates\nrepo: https://github.com/davidenunes/tensorx #link to sources on github\nversion: master #link to sources on github\n\npages:\n - page: \"api/train/model.md\"\n source: \"tensorx/train/model.py\"\n methods:\n - Model:\n - train\n - set_optimizer\n \n - page: \"api/layers/core.md\"\n source: 'tensorx/layers.py'\n classes:\n - Linear:\n - compute_shape\n - Module\n - page: \"math.md\"\n source: 'tensorx/math.py'\n functions:\n - sparse_multiply_dense\n\n # creates an index page based on everything from target source\n - page: \"api/layers/index.md\"\n source: \"tensorx/layers.py\"\n index: True\n````\n\n* **sources_dir**: directory where the resulting markdown files are created\n* **templates_dir**: directory where template files can be stored. All the folders and files are \ncopied to the `sources_dir`. Any markdown files are used as templates with the \ntag `{{autogenerated}}` in the template files being replaced by the generated documentation.\n* **repo**: repository to create `view source` links automatically for each class, function, and method;\n* **version**: defaults to \"master\" to create link to sources in the form `https://repo/blob/version/file.py/#L1425`;\n* **pages**: list of pages to be automatically generated from the respective source files and templates:\n * **page**: path for page template / sources dir for the resulting page;\n * **source**: path to source file from which the page is to be generated;\n * **classes**: list of classes to be fully documented; a list of method names can be passed for each class, the default is\n to generate all methods; \n * **functions**: list of functions to be documented.\n * **index**: if True creates an index page for the given sources, you can also specify classes and functions, but not methods\n \n\n## Buy me a coffee\nIf you find any of this useful, consider getting me some coffee, coffee is great!\n<br/><br/>\n<a href='https://ko-fi.com/Y8Y0RZO6' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://az743702.vo.msecnd.net/cdn/kofi3.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "mkgendocs is a Python tool to automate the generation of documentation from docstrings in markdown",
"version": "0.9.2",
"project_urls": {
"Homepage": "https://github.com/davidenunes/mkgendocs",
"Repository": "https://github.com/davidenunes/mkgendocs"
},
"split_keywords": [
"mkgendocs",
"docs",
"documentation",
"automation",
"mkdocs",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3dd3cb20e728256026d5624d6601224ee418854da1a42c350990c51d03f62b4",
"md5": "83e60711d7eed9329028de998fc74cb4",
"sha256": "4ca8f695aca1741e5fe4728713598eba942447650bf2c84f2c27f33413f57417"
},
"downloads": -1,
"filename": "mkgendocs-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83e60711d7eed9329028de998fc74cb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 15718,
"upload_time": "2022-08-11T23:58:39",
"upload_time_iso_8601": "2022-08-11T23:58:39.596879Z",
"url": "https://files.pythonhosted.org/packages/a3/dd/3cb20e728256026d5624d6601224ee418854da1a42c350990c51d03f62b4/mkgendocs-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fba09505f017d1fe5ca8cffb9849f49aebaa4255301d3bef517494d836608073",
"md5": "7f8a203d97342717c7b5018210732dee",
"sha256": "556784e7d6830b1d9330ec8ca372b7db780eb1083f573b162cbd80f9f493c000"
},
"downloads": -1,
"filename": "mkgendocs-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "7f8a203d97342717c7b5018210732dee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 16539,
"upload_time": "2022-08-11T23:58:40",
"upload_time_iso_8601": "2022-08-11T23:58:40.895503Z",
"url": "https://files.pythonhosted.org/packages/fb/a0/9505f017d1fe5ca8cffb9849f49aebaa4255301d3bef517494d836608073/mkgendocs-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-11 23:58:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davidenunes",
"github_project": "mkgendocs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkgendocs"
}
JSON
