Skip to main content

Sphinx extension for collecting external data for Sphinx build.

Project description

Complete documentation: http://sphinx-collections.readthedocs.io/en/latest/

Welcome to

https://github.com/useblocks/sphinx-collections/raw/master/docs/_static/sphinx_collections_logo.png

Sphinx-Collections is a Sphinx extension to collect and generate additional files from different sources. These files are added to the Sphinx Source Folder, so that Sphinx takes them into account for the overall documentation build.

Sphinx Collections supports multiple collections, where each collection has its own source and target folder, specific configuration and use case based driver.

https://github.com/useblocks/sphinx-collections/raw/master/docs/_static/sphinx_collections_chart.png

A collection can be activated by default or its usage can be triggered by Sphinx tags.

Depending on the usage of a specific collection for a build, its content integration can be controlled by the if-collection:: directive .

Following use cases are supported:

Sphinx-Collections cares about keeping your collection folders clean before and after each build.

Installation

Install via pip: pip install sphinx-collection.

Then add the extension to the conf.py file of the Sphinx project:

extensions = [
    "sphinxcontrib.collections",
    # other extensions
]

Introduction

Sphinx-Collections gets completely configured by variables inside the conf.py file of your Sphinx project:

collections = {
   'my_files': {
      'driver': 'copy_folder',
      'source': '../../extra_files/'
   }
}

The driver copy_folder allows to copy local folders and their files into your Sphinx project. There are other drivers available, which support different use cases and file locations.

By default all files get copied to _collections/ + collection_name, so in this example the complete path inside your documentation folder would be _collections/my_files/. The location can be set specific for each collection by using target option.

Then you can reference the copied files by using a toctree:

.. toctree::
   _collections/my_files/index

Please see the documentation of the needed Driver to know which options are available and necessary.

Tag based collections

Use Sphinx tags to collect and integrate only needed data:

 collections = {
   'my_files': {
      'driver': 'copy',
      'source': '../../extra_files/',
      'tags': ['user_manual'],  # gets active, if "user_manual" is set as tag
      'active': False,  # by default, collection shall not be executed
   }
}

Then run sphinx-build with -t option:

sphinx-build -b html -t user_manual . _build/html

Collection based content

Use if-collection to add content to a page only, if a specified collections has been executed successfully.

.. if-collection:: my_test, my_data

   My Test & Data chapter
   ----------------------

    .. toctree::

      /_collections/my_test/index
      /_collections/my_data/index

For more information take a look into the documentation of if-collection.

Motivation

This sphinx extension is based on the needs of a software development team inside a german automotive company.

The project team was searching for a practical way to support multiple sphinx-based documentations inside a mono-repository and have the possibility to merge different documentations together or to add files based on external data.

Sphinx-Collections is part of a software bundle, which was designed to support the development of ISO 26262 compliant software. Other tools are: sphinx-needs, sphinx-test-reports, tox-envreport.

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-collections-0.2.0.tar.gz (12.9 kB view details)

Uploaded Source

File details

Details for the file sphinx-collections-0.2.0.tar.gz.

File metadata

  • Download URL: sphinx-collections-0.2.0.tar.gz
  • Upload date:
  • Size: 12.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.11.6

File hashes

Hashes for sphinx-collections-0.2.0.tar.gz
Algorithm Hash digest
SHA256 eb266811ca117524919a9f232dd27267a2838d9c0729604f8411ae7eab36f660
MD5 cc85f0c773b9f920100279fcf23e3b42
BLAKE2b-256 f74d6c94cf98457d43e4fed65a25e1cafc0a5250c8e9ce2838ae31c249912400

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