Markdown documentation generator from Google docstrings

Overview

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

Comments
  • Unable to find async functions

    Unable to find async functions

    Love the tool, using it for a few projects.

    Ran into this today that is pretty straightforward, I would surmise that async def func_name() was not included in scope for the original development.

    If i can provide more data or details, please let me know!

    Reproduction of Error

    main.py

    async def a_func() ->> bool:
        """ A Test Func
        
        Returns:
            bool: Returns True always
        """
        return True
    

    mkgendocs.yml

    ---
    sources_dir: docs
    version: main
    
    pages:
      - page: main.md
        source: main.py
        functions:
          - a_func
    

    GenDocs (Fail)

    % gendocs --config mkgendocs.yml
    >Loading configuration file
    >Cleaning up existing sources directory.
    >Populating sources directory with templates.
    >Generating docs ...
    >Building ref index...
    >Generating docs for a_func
    Traceback (most recent call last):
      File "/Users/user/git/project_repository/env/bin/gendocs", line 8, in <module>
        sys.exit(main())
      File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/gendocs.py", line 412, in main
        generate(args.config)
      File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/gendocs.py", line 379, in generate
        fn_info = extract.get_function(fn)
      File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/parse.py", line 637, in get_function
        fn = self._get_function(function_name)
      File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/parse.py", line 681, in _get_function
        raise Exception("function %s not found in %s" % (function_name, self.path))
    Exception: function a_func not found in /Users/user/git/project_repository/main.py
    

    Modify main.py (remove async)

    def a_func() ->> bool:
        """ A Test Func
        
        Returns:
            bool: Returns True always
        """
        return True
    

    GenDocs (Succeed)

    % gendocs --config mkgendocs.yml
    >Loading configuration file
    >Cleaning up existing sources directory.
    >Populating sources directory with templates.
    >Generating docs ...
    >Building ref index...
    >Generating docs for a_func
    >Creating new page with autogenerated content:docs/main.md
    
    bug 
    opened by ip-sf 2
  • feat: custom repo name

    feat: custom repo name

    Allows to define custom repo name for source link (ex: AzureDevOps). In some cases it won't highlight code line, but at least there will be link to file

    opened by AleksandrsKozlov 2
  • Bump mako from 1.2.1 to 1.2.2

    Bump mako from 1.2.1 to 1.2.2

    Bumps mako from 1.2.1 to 1.2.2.

    Release notes

    Sourced from mako's releases.

    1.2.2

    Released: Mon Aug 29 2022

    bug

    • [bug] [lexer] Fixed issue in lexer where the regexp used to match tags would not correctly interpret quoted sections individually. While this parsing issue still produced the same expected tag structure later on, the mis-handling of quoted sections was also subject to a regexp crash if a tag had a large number of quotes within its quoted sections.

      References: #366

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • Modular parser for other docstring types

    Modular parser for other docstring types

    The project looks amazing and I would really like to use it, but sadly I am using numpy docstrings for my documentation. When I have time, I would love to extend the project to support numpy docstrings too, but the code is quite long and it isn't obvious how to extend it properly. Do you have tips on where to start? Maybe the parsers could be implemented in separate files and then called upon depending on what is provided in the documentation 😄

    documentation enhancement 
    opened by SoulEater45 2
  • Add function return type

    Add function return type

    source

    class Xxx():
        def get_xxx(self, arg: str) -> str:
            pass
    

    actual

    Xxx

    Xxx()
    

    Methods:

    .get_xxx

    .get_xxx(
       arg: str
    )
    

    expected

    Xxx

    Xxx()
    

    Methods:

    .get_xxx

    .get_xxx(
       arg: str
    ) -> str
    
    enhancement 
    opened by murata100 0
Owner
Davide Nunes
#AI Researcher I work with neural networks, representation learning, and meaning
Davide Nunes
A python package to avoid writing and maintaining duplicated python docstrings.

docstring-inheritance is a python package to avoid writing and maintaining duplicated python docstrings.

Antoine Dechaume 15 Dec 7, 2022
VSCode extension that generates docstrings for python files

VSCode Python Docstring Generator Visual Studio Code extension to quickly generate docstrings for python functions. Features Quickly generate a docstr

Nils Werner 506 Jan 3, 2023
Pydocstringformatter - A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257.

Pydocstringformatter A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257. See What it does fo

Daniël van Noord 31 Dec 29, 2022
Project documentation with Markdown.

MkDocs Project documentation with Markdown. View the MkDocs documentation. Project release notes. Visit the MkDocs wiki for community resources, inclu

MkDocs 15.6k Jan 2, 2023
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 808 Dec 27, 2022
Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature.

Mark Gillard 109 Dec 7, 2022
Swagger Documentation Generator for Django REST Framework: deprecated

Django REST Swagger: deprecated (2019-06-04) This project is no longer being maintained. Please consider drf-yasg as an alternative/successor. I haven

Marc Gibbons 2.6k Jan 3, 2023
sphinx builder that outputs markdown files.

sphinx-markdown-builder sphinx builder that outputs markdown files Please ★ this repo if you found it useful ★ ★ ★ If you want frontmatter support ple

Clay Risser 144 Jan 6, 2023
MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

Terry Zhao 48 Jan 6, 2023
Jupyter Notebooks as Markdown Documents, Julia, Python or R scripts

Have you always wished Jupyter notebooks were plain text documents? Wished you could edit them in your favorite IDE? And get clear and meaningful diff

Marc Wouts 5.7k Jan 4, 2023
Python syntax highlighted Markdown doctest.

phmdoctest 1.3.0 Introduction Python syntax highlighted Markdown doctest Command line program and Python library to test Python syntax highlighted cod

Mark Taylor 16 Aug 9, 2022
Rust Markdown Parsing Benchmarks

Rust Markdown Parsing Benchmarks This repo tries to assess Rust markdown parsing

Ed Page 1 Aug 24, 2022
Make posters from Markdown files.

MkPosters Create posters using Markdown. Supports icons, admonitions, and LaTeX mathematics. At the moment it is restricted to the specific layout of

Patrick Kidger 243 Dec 20, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
API Documentation for Python Projects

API Documentation for Python Projects. Example pdoc -o ./html pdoc generates this website: pdoc.dev/docs. Installation pip install pdoc pdoc is compat

mitmproxy 1.4k Jan 7, 2023
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 440 Jan 6, 2023
Your Project with Great Documentation.

Read Latest Documentation - Browse GitHub Code Repository The only thing worse than documentation never written, is documentation written but never di

Timothy Edmund Crosley 809 Dec 28, 2022