AutoMacDoc is a tool to generate documentation for Python modules or groups of functions. It is based on MkDocs and written in Python.

To keep it simple:

• The best tool to auto generate a doc is Sphinx but it is complicated and it uses reStructuredText.
• reStructuredText sucks, MarkDown rocks!
• MkDocs is an amazing tool to generate a website with MarkDown.
• We lack a tool to transform a folder of code into a nice and clean MkDocs project

With pip pardi : pip install automacdoc

• Ingredients:

  • a folder with some python codes inside (like the folder example here)
  • nice and well documented functions inside this code

• Easy steps:

  • install automacdoc
  • open a terminal and type automacdoc example/src example

AutoMacDoc list all your python functions and class in the folder (in example/src here) and generate doc about it (in example here)! It creates:

• a 'docs' folder that contains the documentation in markdown (see MkDocs for more details)
• a 'site' folder that contains the static sitePP
• a 'mkdocs.yml' file that in the config file for mkdocs (see MkDocs for more details)

• before AutoMacDoc:

 src/
     ...         # Other python files or folders

• after AutoMacDoc:

 mkdocs.yml      # The configuration file.
 src/
     ...         # Other python files or folders
 docs/
     index.md    # The documentation homepage.
     ...         # Other markdown pages, images and other files.
 site/           # The static site ready to be hosted
     index.html
     ...

Code:

def fun(arg1: int, arg2: str = 'Hello World!'):
    """Description of your function

    **Parameters**

    > **arg1:** `int` -- Description of argument `arg1`.

    > **arg2:** `str` -- Description of argument `arg2`.

    **Returns**

    > `str` -- Description of returned object.
    """
    return arg2 + str(arg1)

Screenshot:

Check the example folder, you will found tons of fancy elements you can now add to your documentation.