Metadata-Version: 2.1
Name: sphinxcontrib-kissapi
Version: 1.0.2
Summary: Simple and flexible python API documentation generation plugin for Sphinx
Home-page: https://github.com/Azmisov/sphinxcontrib-kissapi
Author: Isaac Nygaard
Author-email: ozixtheorange@gmail.com
License: MIT
Description: 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. By default if
              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``.
Keywords: sphinx automatic api generation documentation
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Description-Content-Type: text/x-rst
