Usage¶

Quickstart¶

Apply these changes to your conf.py:

Add jinjaapidoc to the extensions. Preferably before autosummary

Set jinjaapidoc_srcdir to the location of your python source code.

Optional - Set jinjaapidoc_outpudir to the directory for all generated files.

Set autosummary_generate to True.

Include the top-level packages/modules into your documents.

Enable Extension¶

To use Jinja Api Documentation in a project, add it to the extensions in your sphinx conf.py:

extensions = [
  'jinjaapidoc',
]

Important

jinjaapidoc will generate files. Other extensions, such as autosummary might want to process them, so add these extensions afterwards. The autosummary extension will automatically be enabled by jinjaapidoc.

Configuration¶

There are a few config values you can set. The only necessary one is the srcdir:

jinjaapi_srcdir:

REQUIRED! the path to the source directory of your python code.

jinjaapi_outputdir:

directory for generated files. Defaults to the documenation source directory (ussually the directory of conf.py).

jinjaapi_nodelete:

bool - If False, delete the output directory first. Defaults to True.

jinjaapi_exclude_paths:

list - A list of paths to exclude.

jinjaapi_force: bool - If True, overwrite existing files. Defaults to True.

jinjaapi_followlinks:

bool - If True, follow symbolic links. Defaults to True.

jinjaapi_dryrun:

bool - If True, do not create any files. Defaults to False.

jinjaapi_includeprivate:

bool - If True, include private modules. Defaults to True.

jinjaapi_addsummarytemplate:

bool - If True, add autosummary template for classes. Defaults to True.

jinjaapi_include_from_all:

bool - If True, include members of a module or package that are listed in __all__. Defaults to True.

Documenter¶

The jinjaapidoc package provides an additional sphinx.ext.autodoc.ModuleDocumenter: jinjaapidoc.ext.ModDocstringDocumenter. The documenter will only insert the docstring of the module but will not create any index. Use him like this (replace <<package.module>>):

.. automoddoconly:: <<package.module>>

Templates¶

You can use your own templates for rendering the rst files. Add the directory with the templates to templates_path in the conf.py. You can provide a jinjaapidoc.gendoc.MODULE_TEMPLATE_NAME and jinjaapidoc.gendoc.PACKAGE_TEMPLATE_NAME template.

The context for the templates is generated by jinjaapidoc.gendoc.get_context(). Variables you can use are:

package: The top package

module: the module

fullname: package.module

subpkgs: packages beneath module

submods: modules beneath module

classes: public classes in module

allclasses: public and private classes in module

exceptions: public exceptions in module

allexceptions: public and private exceptions in module

functions: public functions in module

allfunctions: public and private functions in module

data: public data in module

alldata: public and private data in module

members: dir(module)

The default template looks like this:

{% block header -%}
:mod:`{{ fullname }}`
======={% for c in fullname %}={% endfor %}
{%- endblock %}

{% block subpackages %}{% if subpkgs -%}
Subpackages
-----------
.. toctree::
   :maxdepth: 3
{% for p in subpkgs %}
   {{ fullname }}.{{ p }}
{%- endfor %}{% endif %}{% endblock %}

{% block submodules %}{% if submods -%}
Submodules
----------
.. toctree::
   :maxdepth: 1
{% for m in submods %}
   {{ fullname }}.{{ m }}
{%- endfor %}{% endif %}{% endblock %}

{% block contents %}{% if ispkg -%}
Module contents
---------------
{%- endif %}

.. automoddoconly:: {{ fullname }}

.. currentmodule:: {{ fullname }}

{% block classsummary %}{% if classes -%}
Classes
~~~~~~~

.. autosummary::
   :toctree: {{ fullname }}
{% for c in classes %}
     {{ c }}
{%- endfor %}{% endif %}{% endblock %}

{% block exceptionssummary %}{% if exceptions -%}
Exceptions
~~~~~~~~~~

.. autosummary::
   :toctree: {{ fullname }}
{% for e in exceptions %}
     {{ e }}
{%- endfor %}{% endif %}{% endblock %}

{% block functionsssummary %}{% if functions -%}
Functions
~~~~~~~~~

.. autosummary::
{% for f in functions %}
     {{ f }}
{%- endfor %}{% endif %}{% endblock %}

{% block datasummary %}{% if data -%}
Data
~~~~

.. autosummary::
{% for d in data %}
     {{ d }}
{%- endfor %}{% endif %}{% endblock %}

{% block functionsdoc -%}
{% for f in functions %}
.. autofunction:: {{ f }}
{%- endfor %}{% endblock %}

{% block datadoc -%}
{% for d in data %}
.. autodata:: {{ d}}
{%- endfor %}{% endblock %}{% endblock %}

Autosummary¶

The default templates use autosummary. Thats why autosummary will be setup automatically. If you already added it to your extensions, make sure it is behind jinjaapidoc. That way, autosummary will also consider the new generated files. Set autosummary_generate to True in your conf.py

By default, custom autosummary templates are added. Right now, there is one for classes. You can set jinjaapi_addsummarytemplate in conf.py to False to avoid that and fall back to the default one. The template looks like this:

{{ fullname }}
{{ underline }}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:
   :undoc-members:
   :show-inheritance:

   {% block methods -%}
   .. automethod:: __init__

   {% if methods -%}
   .. rubric:: **Methods**

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {%- endif %}
   {%- endblock %}

   {% block attributes -%}
   {%- if attributes -%}
   .. rubric:: **Attributes**

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {%- endif %}
   {%- endblock %}