sphinxcontrib-kissapi 1.0.3
Simple and flexible python API documentation generation plugin for Sphinx
License: MIT
Keywords: sphinx automatic api generation documentation

Welcome to Kiss API!
====================

This project is a `Sphinx <https://www.sphinx-doc.org/>`_ plugin for automatically generating python API docs.

Why use this plugin?
--------------------
This plugin takes a different approach than others like `autoapi <https://sphinx-autoapi.readthedocs.io>`_,
`automodapi <https://sphinx-automodapi.readthedocs.io>`_, or plain
`autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_. 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 <https://github.com/Azmisov/sphinxcontrib-kissapi>`_ to build
manually.

.. code-block:: bash

    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_dir : str
    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_dir : str
    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``.
output : dict
    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.
introspect : dict
    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]``:

      .. code-block:: python

        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``:

.. code-block:: python

    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:

.. code-block:: rest

    .. 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``.