Skip to main content

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-automagicdoc-0.0.2.tar.gz (5.8 kB view details)

Uploaded Source

Built Distribution

sphinx_automagicdoc-0.0.2-py2.py3-none-any.whl (7.5 kB view details)

Uploaded Python 2 Python 3

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

Hashes for sphinx-automagicdoc-0.0.2.tar.gz
Algorithm Hash digest
SHA256 eed3a281152d92267dcd36ae0717a3c381e655e5007e50a05997da6e07a64856
MD5 0a67ca0db8032d264910262ad58fa4e0
BLAKE2b-256 5cc62b585cee5fb33be9bc0a533a1ab72d244727b241f1fcbeaa1a0a0c99e5c5

See more details on using hashes here.

File details

Details for the file sphinx_automagicdoc-0.0.2-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_automagicdoc-0.0.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 bf1b7224f37ba7f5a6c47f04b85c091c9565c87f149074d82056f373aa43ee89
MD5 13b36e07ba39913fdd0036570748eaae
BLAKE2b-256 4a9e06ae64ea59a25cc7bc9abffa9e0ca99bf46707f579ab0950b8d8a992c29c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page