This repository holds a ProbLog extensions for Sphinx, designed to be used with the Jupyter Book platform. It implements interactive ProbLog code blocks that can be executed directly in the browser via ProbLog API.
This readme file holds a technical documentation of the sphinx-problog
extension.
For a Jupyter Book usage example of interactive ProbLog code boxes visit
the ProbLog template and its source hosted in the
simply-logical/problog-book-template GitHub repository.
This readme file uses Jupyter Book's MyST Markdown syntax for roles and directives -- see MyST overview for more details. For use with Sphinx, please refer to the reStructuredText syntax.
To get started with sphinx-problog
, first install it via pip
:
pip install sphinx-problog
then, add the problog
module of the sphinx_problog
extension to the Sphinx
extensions
list in your conf.py
...
extensions = ['sphinx_problog.problog']
...
The sphinx_problog.problog
module defines the
problog
directive, which is used for building
interactive ProbLog code boxes executed directly in the browser.
A ProbLog code box is included with the problog
directive:
```{problog} problog:1.2.3
optional :- content.
```
Each ProbLog code box can be referenced with its name using the ref
role, e.g., {ref}`problog:1.2.3`
, which produces ProbLog code box
hyper-link.
The problog
extension uses the following Sphinx configuration parameters:
sphinx_problog_code_directory
(required when loading the box content from a file) -- defines the path to a directory holding files with content (ProbLog code) of each ProbLog code box; andsphinx_problog_execution_server_url
(optional) -- specifies the URL of the ProbLog execution server (ProbLog API, https://verne.cs.kuleuven.be/problog/api/ by default, which is hard-coded in the ProbLog JavaScriptproblog_editor_advanced.js
).
Each ProbLog code box has one required argument that
specifies the unique id of this particular interactive code block.
This id must start with the problog:
prefix.
The content of a ProbLog box can either be provided explicitly within the
directive, or -- when the content is left empty -- it is pulled from a code
file whose name is derived from the code box id, and which should be located in
the directory specified via the sphinx_problog_code_directory
configuration
parameter.
The code file name is expected to be the code block id without the
problog:
prefix and with the .pl
extension.
For example, for a code block with problog:my_code
id, the code file should
be named my_code.pl
.
The problog
Sphinx extension monitors the code files for
changes and automatically regenerates the affected pages.
The CSS and JS files used by this Sphinx extension (namely
sphinx-problog.css
,mode-problog.js
andproblog_editor_advanced.js
, as well as their CDN-pulled dependenciesace.js
,jquery.min.js
,jquery-ui.min.js
andmd5.js
) can be found in thesphinx_problog/_static
directory of this repository.