.rst 👉 🔧 👉 .json

The deconst Sphinx preparer builds Sphinx documentation into custom JSON metadata envelopes. It's intended to be used within a CI system to present content to the rest of build pipeline.

To run the Sphinx preparer locally, you'll need to install Docker for your platform.

Once you have Docker set up, export any desired configuration variables and run deconst-preparer-sphinx.sh with the absolute path to any Sphinx-based content repository.

./deconst-preparer-sphinx.sh /absolute/path/to/content-repo

The following values may be present in the environment:

• CONTENT_ROOT is a path containing Sphinx content to prepare. Default: $(pwd)
• ENVELOPE_DIR is the destination directory for metadata envelopes. Default: $(pwd)/_build/deconst-envelopes/
• ASSET_DIR is the destination directory for referenced assets. Default: $(pwd)/_build/deconst-assets/
• CONTENT_ID_BASE is a prefix that's unique among the content repositories associated with the target deconst instance. Our convention is to use the base URL of the GitHub repository. Default: Read from _deconst.json

By default, the preparer will use the deconst-serial builder, which will generate a separate HTML file for every ReST file in your repository. This behavior is similar to running make html. If you would rather generate a single HTML file with the contents of your entire repo (à la make singlehtml), you must add the following line to your conf.py file:

builder = 'deconst-single'

The deconst_default_unsearchable property may be set to True to exclude all content from this content repository from being indexed for search.

deconst_default_unsearchable = True

One or more page categories can be specified for the entire content repository at once with the deconst_categories property. These are useful for constraining search results and may be used by site templates.

deconst_categories = ['global category one', 'global category two']

The Sphinx preparer offers page-level customization by reading per-page metadata that's present on each page.

The page title offered to Deconst templates may be overridden with the deconsttitle attribute:

:deconsttitle: Not the Sphinx title

This is especially important for your index.rst file, which by default generates a title of "< no title >".

Set additional categories for individual pages with the deconstcategories attribute. Use a comma-separated list of category names. Whitespace will be trimmed from each category.

:deconstcategories: page category one, page category two

Individual pages can be excluded from search indexing with the deconstunsearchable attribute. Use the string true to exclude a specific page.

:deconstunsearchable: true