Generate Documentation Automatically

Documentation Status PyPI Build Status GitHub

This is a Python package for automatically building the documentation pages to document a given Python package using Sphinx. gendocs allows users to keep all of their documentation directly within their packages as pages are generated directly from the docstrings in the code!

Connections

Want to see examples? Check out one of the following projects which use gendocs:

  • PVGeo: A Python package for visualizing geophysical data in VTK and ParaView
  • ESPA Tools: A Python package for simple loading of Landsat imagery as NumPy arrays

Get Started

Install gendocs from PyPI:

$ pip install gendocs

Cookiecutter

Want to easily create a new project that will build its own documentation? Try the gendocs Cookiecutter which will prompt you for your new project’s details and create all the needed file structures for your new, automatically documented Python package.

To create a new project, make sure you have Cookiecutter installed in your virtual environment:

$ pip install cookiecutter

Now you can use our Cookiecutter template to create a new project ready for gendocs by executing the following command and following the prompts:

$ cookiecutter https://github.com/banesullivan/cookiecutter-gendocs.git

That’s it! Now you have a new Python project ready for automatic documentation and deployment.

Usage

Already have a Python package in need of automatic documentation? Follow these steps.

This generator is built for Sphinx (RST) documentation. To document your package, setup sphinx and a conf.py then add the following somewhere near the top of your conf.py:

# Import the package to document:
import wonderfulpackage

# Automatically generate documentation pages
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage)

That’s it! That code block above is all you need to do to document your package(s) thoroughly. Now you can build the Sphinx documentation, and all docs pages will be automatically generated.

Remove the Edit on GitHub Button

Be sure to remove the Edit on GitHub link from your project by following these steps.

Make Your Own Homepage

Note that you can also set up a base index file in your project for the Generator to append if you’d like to include a brief overview of the package. We simply pass the filename of our README to the DocumentPackages method.

Let People Know

If your project generates documentation automatically, please add a badge to your project to let people know! We hope that these badges will stir curiosity, involvement, and community contributions to the gendocs package.

Markdown:

[![Documentation Built by gendocs](https://img.shields.io/badge/docs%20by-gendocs-blue.svg)](https://gendocs.readthedocs.io/en/latest/)

RST / Sphinx:

.. image:: https://img.shields.io/badge/docs%20by-gendocs-blue.svg
   :target: https://gendocs.readthedocs.io/en/latest/
   :alt: Documentation Built by gendocs

Contribute

Check out gendocs of GitHub to Contribute and make automatic documentation even better!

About gendocs

  • Author: Bane Sullivan
  • License: BSD-3-Clause
  • Copyright: 2018, Bane Sullivan
  • Version: 0.4.0

gendocs: Automatically build documentation pages for a Python package.

This package allows developers to document there libraries as they code so that they do not have to worry about organizing Sphinx documentation pages. gendocs does this by creating an intuitive documentaition structure that mimics the given package’s file structure.

generator

This provides all of the functionality behind gendocs and contains the Generator class which is what you will need to use if you would like to start automatically documenting your packages.

Conventions

For gendocs to work properly, we have re-defined the idea of packages and modules for the sake of gendocs. A package can contain just about anything: classes, functions, modules, sub-module, etc.; while a module in the traditional sense can do the same, we re-define modules not to contain any further sub-modules. This re-definition allows gendocs to mimic the structure of a Python package and automatically generate documentation pages containing the docstrings for the package!

What to Include

For gendocs to work, every module being documented MUST contain an __all__ variable defining what is available to be documented. This variable ensures gendocs does not recurse through external packages you might use internally.

Make sure to include an __all__

Note that only what is defined in this module’s __all__ list is what is accessible and what gets documented. Without an __all__ the documentation build will fail.

Some optional variables:

  • __displayname__ (str): include this attribute to change how the heading for any documented element is displayed
  • __category__ (str): if any documented element contains this attribute, a statistics table is generated on the home page to count occurrences of various categories.
A Simple Use Case

If you only want to put up the documentation for your package, then set up sphinx documentation using sphinx-quickstart (details) and stop after you’ve generated a new conf.py. Edit the parameters of your configuration file appropriately and then add the following somewhere near the top:

# Import the package to document:
import wonderfulpackage

# Automatically generate documentation pages
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage)

That’s all you have to do! Now you can push your changes to a continuous integration like Read the Docs and have your entire package automatically documented.

Remove the Edit on GitHub

Be sure to remove the Edit on GitHub link from your project by following these steps.
Sophisticated Use Case
Private Members

It’s worth noting that you can control how private features are documented by passing an argument to the DocumentPackages method:

# Import the package to document:
import wonderfulpackage

# Automatically generate documentation pages and show private members
from gendocs import Generator
Generator().DocumentPackages(wonderfulpackage, showprivate=True)
Custom Homepage

To use your own homepage to provide a project overview then create a .rst file containing the content for your homepage and paste the relative file name to the DocumentPackages method (we use our README for convenience):

# Import the package to document:
import wonderfulpackage

# Automatically generate documentation pages and show private members
from gendocs import Generator
gen = Generator()
gen.DocumentPackages(wonderfulpackage,
                     index_base='../../README.rst',
                     showprivate=True
                    )
Classifier
class gendocs.generator.Classifier[source]

Bases: object

static GetClassText(heading, name, showprivate=False, showinh=False)[source]

Returns the needed text to automatically document a class in RSF/sphinx

static GetFunctionText(heading, name)[source]

Returns the needed text to automatically document a function in RSF/sphinx

static GetModuleText(heading, name, showprivate=False)[source]

Returns the needed text to automatically document a module in RSF/sphinx

Generator
class gendocs.generator.Generator(**kwargs)[source]

Bases: properties.base.base.HasProperties

An object to assist in the automatic generation of documentation pages
for a given package. These methods iterate over a package and document each submodule as their own page. This class handles packages and modules in a very specific manner: - packages contain modules, classes, and functions - modules cannot contain sub-modules but only classes and functions

Required Properties:

  • path (String): The top level directory to store all documentation content., a unicode string, Default: content
DocumentPackages(packages, index_base=None, showprivate=False, notify=True, showinh=False, intro_pages=None, append_material=None, extra=None)[source]

This is the high level API to use to generate documentation pages for any given package(s).

Parameters:
  • packages (list(module)) – A list of packages that contain submodules to document
  • index_base (str) – The index page file name. This content will be appended
  • showprivate (bool) – A flag for whether or not to display private members
static OpenIndex(filename)[source]
static WriteIndex(index)[source]
_DocPackageFromTop(packages, showprivate=False, showinh=False)[source]

Generates all of the documentation for given packages and appends new tocrees to the index. All documentation pages will be under the set relative path.

Parameters:
  • packages (list(module)) – A package or list of packages that contain submodules to document
  • showprivate (bool) – A flag for whether or not to display private members
Returns:

The new content to append to the index
Return type:

str
_GenerateStaticsTable(title='Current Statistics')[source]

Generates a statics table based on set categories

_MakePackagePages(package, showprivate=False, nested=False, showinh=False)[source]

An internal helper to generate all of the pages for a given package

Parameters:
  • package (module) – The top-level package to document
  • showprivate (bool) – A flag for whether or not to display private members
  • nested (bool) – Foor internal use ONLY
Returns:

The file names ready to be appended to a top-level toctree
Return type:

str
_ProduceContent(mods, showprivate=False, showinh=False)[source]

An internal helper to create pages for several modules that do not have nested modules. This will automatically generate the needed RSF to document each module module and save the module to its own page appropriately.

Parameters:
  • mods (module) – The modules to document that do not contain nested modules
  • showprivate (bool) – A flag for whether or not to display private members
Returns:

The file names ready to be appended to a toctree
Return type:

str
_ProduceSingleContent(mod, showprivate=False, showinh=False)[source]

An internal helper to create a page for a single module. This will automatically generate the needed RSF to document the module and save the module to its own page in its appropriate location.

Parameters:
  • mod (module) – The single module to document as its own page
  • showprivate (bool) – A flag for whether or not to display private members
Returns:

The file name ready to be appended to a toctree
Return type:

str
_class_validators = {'_validate_props': <properties.handlers.ClassValidator object at 0x7fdeac416c90>}
_defaults = {}
_prop_observers = {}
_props = {'path': <properties.basic.String object at 0x7fdeac3b2bd0>}
path

path (String) – The top level directory to store all documentation content., a unicode string, Default – content