docfly Quick Start

docfly helps you to reduce duplicate works building your documentation website with sphinx-doc. The killer features are:

  • Automatically generate API reference document with a few line of codes

  • Automatically generate table of content (the .. toctree:: directive) and the reference code to the sub documents.

Auto API Reference Document

There’s a Sphinx doc feature that can automatically extract docstring from your source code, and generate API doc for you to search, reference. Howevery, you still need to declare which package / module / class / method / function you want to include. It could be 1,000+ line of code to maintain in large project.

Giving a package name, docfly can automatically generate those declaration files for your package, and keep your reference up-to-date when source code changes. You can find the example here.

Usage

It’s eazy, just add following code snippet to your conf.py file:

import docfly

#--- Api Reference Doc ---
package_name = docfly.__name__

docfly.ApiReferenceDoc(
    conf_file=__file__, # locate the path of conf.py
    package_name=package_name, # specify which package you want to generate api doc for
    ignored_package=[ # specify sub package / module you want to ignore
        "%s.pkg" % package_name,
    ]
).fly()

Basically it does three things:

  1. tell docfly where is the conf.py file. So it can generate the .rst file accordingly.

  2. tell docfly which package you want to generate api doc for.

  3. tell docfly which sub package / module you want to ignore

Auto Table Of Content

A documentation website like a book. It usually use a hierarchy structure like Chapter, Section, … We expect that it automatically generate the hyperlink from top to bottom.

The sphinx-doc official doc shows that you need to put this directive at where you want to generate table of content:

.. toctree::
    :maxdepth: 1

    Title of your sub document <path-to-the-rst-file> # manual work
    ...

In other word, you still need to manually specify the title and path to the sub document, and you need to update the toc when sub documents changed.

The other docfly killer feature is that it provides a new directive .. autotoctree:: can automatically generate the underlying .. toctree:: directive for you if you are following the Sphinx Style Guide.

Usage

Add the following code snippet to conf.py:

extensions = [
    ...
    'docfly.directives', # enable docfly directives
    ...
]