sphinx-collections 0.0.1a1

Introduction

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

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

The driver copy allows to copy local files into your Sphinx project. There are other drivers available, which support different use cases and and files 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