autoflex

autoflex#

A flexible, nicer way of generating API docs without requiring custom docstrings.

This extension aims to do that.

Get Started#

Install#

autoflex is designed to be intentionally easy to install via pip and use within your project

pip install autoflex

In your documentation project conf.py:

extensions = [
   ...
   "autoflex",
   ...
]

That’s it!

Usage Overview#

Extension Command

Brief Description

Specification

autoflex

Our very extensible, automatic API documentation generator for classes.

flexsummary

A customizable autosummary directive using autoflex constructors.

flexcompute/autoflex#10

Basic autoflex Usage#

If you just want to automatically generate the API documentation for a class with the default configuration by the extension. You need to make sure you’ve delclared the relevant top path of the module you’re in.

.. currentmodule:: tidy3d

.. autoflex:: tidy3d.Simulation

Basic flexsummary Usage#

Custom autosummary implementation, based on autoflex directives.

.. flexsummary::

Objectives#

  • Improve the API template for autodoc which can be limited.

  • For each class, such as tidy3d complex classes, properly generate a nicer template of the parameters and methods that extends how autodoc works.

  • Generate an index of each API directive that can be easily searched by corresponding themes like the sphinx_book_theme.

  • For inherited classes, have the option to easily define the methods and parameters that we want to generate documentation for.

  • Have the option to generate custom HTML relevant to each class in a way defined by the class docstring.

  • Make sure the docstrings don’t interfere with help messages such as ipython, etc. (Maybe explore how to compile relevant docstrings into the help messages).

API Docstrings Improvements

When we have highly complex classes that have multiple inherited parameters, it is desired to have a clear definition of each specific class and its parameters, types, and defaults. Whilst this can be done manually for an individual class or method, as a project increases in complexity, it is desired to understand the relevant docstrings for each class and method.

Implementation Methodology#

  • Validated static data container Descriptor types are used to construct the structures which are represented in HTML.

  • Automated sphinx extensions is used to extract the corresponding data types from a given class implementation.

Indices and tables#

Contents