autoflex Sphinx Documentation ExtensionA flexible, nicer way of generating API docs without requiring custom docstrings.
One of the main complexities we have is that managing rst code blocks in docstrings is complicated. It involves manually writing and updating parameter descriptions rather than focusing on the actual docstrings.
When we have multiple classes, and multiple inherited classes, it is hard to keep track of each code block and all the added parameters. For example, it would be possible to manually input parameters at each particular stage. However, it would be nice if this could be extracted directly out of each class declaration automatically and render it in a nice way.
This extension aims to do that.
autodoc which can be limited.tidy3d complex classes, properly generate a nicer template of the parameters and methods that extends how autodoc works.sphinx_book_theme.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.
The idea is that we can use the autoflex directive to improve the data structure generated during the autosummary process instead of the automodule or autoclass directive.
Install the package in development mode:
poetry install -E devBuild the local basic documentation with the extension linked:
poetry run python -m sphinx docs/ _docs/Basic Example:
.. autoflex:: somepackage.BasicClass # CURRENTLY NOT WORKING