sphinx-prolog Extension

The sphinx-prolog extension implements four modules:

• infobox responsible for creating admonition-styled information boxes that are referenceable and may be given a title – described in the Information Boxes section;

• pprolog implementing custom Prolog syntax highlighting for code boxes – described in the Pseudo Prolog Syntax Highlighting section;

• solex enabling creation of automatically numbered, referenceable and linked admonition-styled exercise and solution boxes – described in the Exercise and Solution Blocks section; and

• swish allowing to incorporate interactive SWI Prolog SWISH-based code and query boxes – described in the SWISH Code and Query Blocks section.

These modules add useful functionality when building Prolog-infused educational – teaching and self-study – content with Sphinx and Jupyter Book.

Note

This guide is written for sphinx-prolog version 0.5.

Tip

In addition to Prolog, the sphinx-prolog package can be used to build documents with interactive cplint code blocks. More information can be found at http://cplint-template.simply-logical.space/.

Installation

The sphinx-prolog extension source code is hosted in the simply-logical/sphinx-prolog GitHub repository. It is distributed via the Python Package Indexer (PyPI) and can be installed with pip by executing

pip install sphinx-prolog

Usage

To use the functionality implemented by this extension, first you need to enable the desired modules in your Jupyter Book or Sphinx configuration file. In Jupyter Book this is achieved by adding the selected extension module names under the sphinx.extra_extensions key in the _config.yml file.

sphinx:
  extra_extensions:
    # Load sphinx-prolog <https://github.com/simply-logical/sphinx-prolog>
    - sphinx_prolog.infobox
    - sphinx_prolog.pprolog
    - sphinx_prolog.solex
    - sphinx_prolog.swish

In Sphinx, extensions are enabled by placing the module names in a Python list stored under the extensions variable in the conf.py file.

...
extensions = ['sphinx_prolog.infobox',
              'sphinx_prolog.pprolog',
              'sphinx_prolog.solex',
              'sphinx_prolog.swish',
              ]
...

Documentation

The technical documentation of the sphinx-prolog extension can be found in its GitHub repository in the README.md file. This page and the following sections, on the other hand, are a practical user guide sprinkled with actual usage examples for each module implemented by the extension. Here, we focus on the Jupyter Book platform and its MyST Markdown syntax, but the same functionality is available directly in Sphinx with its reStructuredText syntax.