Metadata-Version: 1.1
Name: sphinx-collections
Version: 0.0.1a1
Summary: Sphinx extension for collecting external data for Sphinx build.
Home-page: http://github.com/useblocks/sphinx-collections
Author: team useblocks
Author-email: info@useblocks.com
License: MIT
Download-URL: http://pypi.python.org/pypi/sphinx-collections
Description: **Complete documentation**: http://sphinx-collections.readthedocs.io/en/latest/
        
        .. image:: docs/_static/sphinx_collections_logo.png
           :align: center
        
        .. From here shared with index.rst of docs folder. #SHARED_CONTENT
        
        Sphinx-Collections
        ==================
        
        ``Sphinx-Collections`` is a Sphinx extension to collect and generate additional files from different sources before
        Sphinx starts the overall build.
        
        All collected and generated files get registered to the Sphinx Env and are therefore available during a Sphinx build.
        
        It was created to support the following use cases:
        
        * Grab additional ``.rst`` or ``md`` files from outside the ``docs`` source folder.
        * Merge multiple Sphinx projects into one project
        * Generate ``.rst`` and ``.md`` files based on data on ``json`` files.
        
        Internally ``Sphinx-Collections`` is based on a set of ``drivers``, which support different use cases.
        Feel free to extend the list of available ``drivers`` by creating a PR in our github project.
        
        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.
        
        .. code-block:: rst
        
            .. if-collection:: my_test, my_data
        
               My Test & Data chapter
               ----------------------
        
                .. toctree::
        
                  /_collections/my_test/index
                  /_collections/my_data/index
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
