A plugin to automagically create autodoc-based API documentation files on the fly
Project description
sphinx-automagicdoc
Description
This plugin can create API documentation stubs (akin to sphinx-autogen), with the significant difference that the creation is done dynamically and on the fly, and the files remain virtual and are monkey-patched into Sphinx IO routines.
Creating a whole set of files matching the structure of a module violates DRY (don't repeat yourself) and enhances the risk of documentation becoming out of sync during e.g. refactorings. Therefore, sphinx-automagicdoc
can be used to dynamically source the rST structure from the Python source as the single source of truth.
Based upon the monkey patched virtual filesystem, additionally, other files or strings can be injected into the Sphinx tree.
Usage
# e.g. added to conf.py
# name the modules automagicdoc should process
automagic_modules = ["nameOfYourPackage"]
automagic_ignore = ["*test*"]
# README.rst and LICENSE from the root directory (outside of doc directory)
# will appear available as README.rst and LICENSE.rst inside doc/
automagic_copy_files = {
"README.rst", "README.rst",
"LICENSE.rst": "LICENSE",
}
# index.rst's content is based upon a string
automagic_files = {
"index.rst": """
Welcome to the documentation!
=============================
.. toctree::
:maxdepth: 1
:caption: Contents:
README
LICENSE
nameOfYourPackage
"""
}
Example
This repo builds its documentation using sphinx-autopyproject as described in .github/workflows/doc.yml
using Github Actions and deploys to Github pages.
See also
sphinx-autopyproject to use pyproject.toml
instead of conf.py
.
License
MIT
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinx-automagicdoc-0.0.2.tar.gz
.
File metadata
- Download URL: sphinx-automagicdoc-0.0.2.tar.gz
- Upload date:
- Size: 5.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | eed3a281152d92267dcd36ae0717a3c381e655e5007e50a05997da6e07a64856 |
|
MD5 | 0a67ca0db8032d264910262ad58fa4e0 |
|
BLAKE2b-256 | 5cc62b585cee5fb33be9bc0a533a1ab72d244727b241f1fcbeaa1a0a0c99e5c5 |
File details
Details for the file sphinx_automagicdoc-0.0.2-py2.py3-none-any.whl
.
File metadata
- Download URL: sphinx_automagicdoc-0.0.2-py2.py3-none-any.whl
- Upload date:
- Size: 7.5 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf1b7224f37ba7f5a6c47f04b85c091c9565c87f149074d82056f373aa43ee89 |
|
MD5 | 13b36e07ba39913fdd0036570748eaae |
|
BLAKE2b-256 | 4a9e06ae64ea59a25cc7bc9abffa9e0ca99bf46707f579ab0950b8d8a992c29c |