.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