Skip to main content

mkgendocs is a Python tool to automate the generation of documentation from docstrings in markdown

Project description

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.

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

Installation

Install mkgendocs from PyPI

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

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!

Buy Me a Coffee at ko-fi.com

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

mkgendocs-0.9.2.tar.gz (16.5 kB view details)

Uploaded Source

Built Distribution

mkgendocs-0.9.2-py3-none-any.whl (15.7 kB view details)

Uploaded Python 3

File details

Details for the file mkgendocs-0.9.2.tar.gz.

File metadata

  • Download URL: mkgendocs-0.9.2.tar.gz
  • Upload date:
  • Size: 16.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.14 CPython/3.10.5 Linux/5.18.7-arch1-1

File hashes

Hashes for mkgendocs-0.9.2.tar.gz
Algorithm Hash digest
SHA256 556784e7d6830b1d9330ec8ca372b7db780eb1083f573b162cbd80f9f493c000
MD5 7f8a203d97342717c7b5018210732dee
BLAKE2b-256 fba09505f017d1fe5ca8cffb9849f49aebaa4255301d3bef517494d836608073

See more details on using hashes here.

File details

Details for the file mkgendocs-0.9.2-py3-none-any.whl.

File metadata

  • Download URL: mkgendocs-0.9.2-py3-none-any.whl
  • Upload date:
  • Size: 15.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.14 CPython/3.10.5 Linux/5.18.7-arch1-1

File hashes

Hashes for mkgendocs-0.9.2-py3-none-any.whl
Algorithm Hash digest
SHA256 4ca8f695aca1741e5fe4728713598eba942447650bf2c84f2c27f33413f57417
MD5 83e60711d7eed9329028de998fc74cb4
BLAKE2b-256 a3dd3cb20e728256026d5624d6601224ee418854da1a42c350990c51d03f62b4

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page