reStructuredText content in Sphinx¶

Sphinx is a documentation builder that assembles reStructureText source files into cohesive output that includes tables of contents, cross-references, and integrated navigation.

Deconst uses native Sphinx code as much as possible, which means that you can mostly use write regular Sphinx documentation, even using extensions or custom directives, without worrying too about the Deconst integration. Exceptions to this are described below.

Assets¶

To integrate properly with Deconst’s asset pipeline:

Place any images in an _images directory at the top level of your Sphinx documentation.

Reference images in .rst files by including a .. image macro.

.. image:: /_images/deconst-initial.png

Tables of contents¶

Native Sphinx uses toctree directives to both control overall documentation structure and flow and generate intelligent tables of contents. These still work within Deconst, but, depending on your template’s needs, you may need to be aware of some special considerations.

First of all, if you wish to allow Deconst’s templates to handle table of contents rendering entirely, you’ll likely want to hide the tables of contents within the page content itself. To do this, add the :hidden: argument to the directive.

.. toctree::
   :hidden:

   one
   two
   three

When using the deconst-serial builder, each page of output will have two relevant tables of contents: a local table of contents that consists of anchor links within the local page, and a repository-wide table of contents for the entire content repository. The repository-wide table of contents is generated by rendering just the .. toctree directive from the Sphinx master document (by default, index.rst), ignoring any :hidden: arguments encountered. Any additional arguments, such as :maxdepth:, will be respected.

To exercise more control over the generated table of contents, create a file called _toc.rst. If _toc.rst exists, it is used instead of the .. toctree directive from the master document. The _toc.rst file can contain whatever markup you wish to use as your table of contents.

:orphan:

This is a headline
==================

.. toctree::
   :maxdepth: 4

   one/index
   two/index
   three/index
   four/index

Extensions¶

To use extensions beyond the ones built in to Sphinx itself, add a requirements.txt or deconst-requirements.txt file to the directory that contains your conf.py and _deconst.json files. List the dependencies that provide the extensions you wish to use, using the same format that pip expects.

If both requirements.txt and deconst-requirements.txt are present, deconst-requirements.txt is used. This allows you to specify different dependencies for local Sphinx builds and for Deconst preparer builds if necessary.

Warning

Be careful if you specify a dependency on Sphinx itself. If the version you specify conflicts with the one used by the Sphinx preparer, your build may break. If you wish to have a Sphinx dependency to make local Sphinx workflows easier, consider extracting other dependencies into an explicit deconst-requirements.txt file to avoid collisions.

Special per-page metadata¶

Sphinx offers page-level customization by reading per-page metadata that may be present on each page. Certain fields can be used to customize Deconst’s output.

deconsttitle¶

If present, a :deconsttitle: field will be used as the page title within Deconst templates rather than the one that Sphinx assigns each document, which is always the top-level heading.

:deconsttitle: Custom Title

This heading will appear on the page, but not in the title
==========================================================

deconstcategories¶

Specify one or more categories to apply to an individual page with the :deconstcategories: field. The field’s value is split on commas and whitespace is trimmed from each element.

:deconstcategories: one, two

Categories redundant with repository-global ones will be deduplicated.

deconstunsearchable¶

Exclude a page from search results by marking it with a :deconstunsearchable: item. This overrides the deconst_default_unsearchable repository-wide setting for this document.

:deconstunsearchable: true

Other metadata¶

Any other fields included here are available to template authors within the deconst.content.envelope.meta structure. Co-ordinate with your template designers to ascribe whatever meaning to other fields that you wish!

conf.py settings¶

Repository-wide settings for Sphinx are managed by a conf.py file at the root of your Sphinx content. Deconst uses several custom settings within this file for its global configuration as well.

builder¶

Deconst supports two distinct builders that alter the way that envelopes are generated, roughly corresponding to Sphinx’s serial (make html) and single-page (make singlehtml) HTML builders. The deconst-single builder assembles all content from the repository into a single page, while the deconst-serial builder creates a different page for each .rst document.

The deconst-serial builder is the default. To use the single builder instead, set the builder variable within your conf.py.

builder = 'deconst-single'
# OR:
builder = 'deconst-serial'

deconst_default_unsearchable¶

To exclude all envelopes within a content repository from search indexing, set deconst_default_unsearchable to True:

deconst_default_unsearchable = True

Notice that this may still be overridden by individual envelopes with per-page metadata.

deconst_categories¶

To apply one or more categories to all pages within your repository, specify them as deconst_categories:

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