sphinxcontrib-kissapi 1.0.3

Simple and flexible python API documentation generation plugin for Sphinx

Welcome to Kiss API!

This project is a Sphinx plugin for automatically generating python API docs.

Why use this plugin?

This plugin takes a different approach than others like autoapi, automodapi, or plain autodoc. I found that these other plugins did a pretty good job of automatically generating API docs, but it was never perfect. They wouldn’t know exactly what to include in the docs, and there just weren’t enough customization options to get what I needed.

Instead of generating the docs automatically, this plugin provides a simple, flexible API for analyzing and introspecting your python code. Using the API, you can generate reST documentation yourself however you want! Keep it simple, stupid.

I’ve also included a default “renderer” which will generate reST documentation automatically. You can use that if you are satisfied with the output and don’t need any additional customization.

Usage

Install the package via pip. See also the source on github to build manually.

pip install sphinxcontrib-kissapi

Inside your sphinx conf.py file, first add sphinxcontrib.kissapi to extensions. KissAPI is integrated to use sphinx’s builtin autodoc and autosummary to extract documentation for introspected variables if desired, so you’ll need to add those dependencies too.

Second, we need to configure what package(s) KissAPI should introspect and how you want to render that package data. This is configured by setting options inside the kissapi_config dict variable. The following options are supported:

out_dirstr

Output directory for files generated by renderer. Default value is "kissapi_output".

overwrite

Whether to overwrite out_dir. This can be one of three values:

1. True: delete folder and completely rebuild

2. False: don’t do anything if folder is found, keep as is

3. "partial": allow files to be overwritten, but don’t delete out_dir completely

jinja_dirstr

A directory with jinja templates, which allows you to use some helpers on the RenderManager class for easier reST file generation. If a relative path is given, it will be relative to the sphinx root docs folder. By default, this is set to sphinxcontrib/kissapi/def_templates directory, which are some default jinja templates I have made to go along with the default renderer (sphinxcontrib.kissapi.def_render).

jinja_env

A custom Jinja environment to use instead of using jinja_dir.

outputdict

This is the main config option for specifying what automatic documentation you want to generate. This dict is a mapping from a unique output name to output config options: {out_name: out_config, ...}. The config options are also a dict, with the following values:

• package (str): The package to be introspected and rendered. See the introspect config value for customizing introspection behavior. Provide the module name as a string.

• render (callable): A callback with signature (mgr:RenderManager, pkg:PackageAPI). The second arg is the introspection results for the package, and you can use its API to examine the modules, classes, functions, variables, and information about them through there. The RenderManager instance has several methods to help you write reST files and use your jinja templates.

  The callback can return a string or list of reST nodes that should be stored as out_name inside the RenderManager if you wish. These can later be injected into your pre-existing reST documents. However, this is not required.

  How you render the package is entirely up to you. A default renderer that I have written for one of my projects is available at sphinxcontrib.kissapi.def_render.pkg_template, and I’m pleased with the docs it generates. Feel free to use or modify it for your own project.

introspectdict

Specify options for customizing how a package is introspected. Similar to output, it is a mapping from package name to config options: {package_name: introspect_config, ...}. The config options are specified as a dict with the following optional values:

• package_exclude: A callback with signature (pkg_name:str, module_name:str) -> bool. It should return True if the module (e.g. from sys.modules) should be excluded from the package and marked as an “external” module. You can also return any other truthy value to exclude the module, but not mark it as external. Variables that are referenced in both your package and an external module will show up True when is_external is called.

  If this callback is not provided, PackageAPI.default_package_exclude is used; this default method excludes modules not prefixed by "[pkg_name].", or contain a private module somewhere in the path (e.g. prefixed by underscore, such as mypackage._private.submodule). Note that only non-exluded modules get introspected by KissAPI.

• var_exclude: A callback with signature (pkg:PackageAPI, parent:VariableValueAPI, value:VariableValueAPI, name:str) -> bool. KissAPI uses the notion of a variable reference, which is parent context and variable reference name. For example in the following code snippet, there are two references to list [1,2,3]:

  baz = [1,2,3]
  class Foo:
      bar = baz

  The first reference is in the globals of the module itself with the name baz. The second reference is inside class Foo with name bar. The “parent” in this example is either the module or class; the “value” is [1,2,3]; the “name” is either baz or bar depending on the parent.

  What this option allows you to do is specify what variable references should be analyzed and which should be skipped. By default if not provided, PackageAPI.default_var_exclude is used; this default method excludes private (prefixed by a single underscore) and external (detected in non-package modules) variables.

Altogether, here is an example of the code you might put in conf.py:

extensions = ["sphinx.ext.autodoc","sphinx.ext.autosummary","sphinxcontrib.kissapi",'sphinx_rtd_theme']

from sphinxcontrib.kissapi.def_render import package_template
kissapi_config = {
    "overwrite": True,
    "output": {
        "my_rendered_output":{
            "package":"my_package",
            "render":package_template
        }
    }
}

If the render callback were to output values, they can be referenced in your existing reST documentation using the kissapi directive. For the above conf.py example, we could inject "my_rendered_output" by adding this directive somewhere:

.. kissapi:: my_rendered_output

API

I still need to setup a ReadTheDocs site and write a more in-depth usage guide. Until then, reference the docstrings for the classes, in particular from introspect.py and manager.py.