mkgendocs


Namemkgendocs JSON
Version 0.9.2 PyPI version JSON
download
home_pagehttps://github.com/davidenunes/mkgendocs
Summarymkgendocs is a Python tool to automate the generation of documentation from docstrings in markdown
upload_time2022-08-11 23:58:40
maintainer
docs_urlNone
authorDavide Nunes
requires_python>=3.7,<4.0
licenseApache-2.0
keywords mkgendocs docs documentation automation mkdocs cli
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ## 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.
 
![mkgendocs](mkgendocs.png)

## 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![mkgendocs](mkgendocs.png)\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"
}
        
Elapsed time: 0.43749s