Help files

Help files, such as this page, are managed using the readthedocs help page system.

The help files are created as .rst (reStrucuredText) files and then compiled using Sphinx to create a viewable set of help pages. Sphinx is able to take the .rst files and produce help files in maultiple different formats (html, pdf etc) but the enterobase help files are primarily for creating the help files in html format.

An Enterobase readthedocs account has been created on with the username WarwickBioinformaticsRTP, Email address for managing the automatic generation of help pages at

The Enterobase project has been setup to create web pages from the ‘latest’ commit to the repository at on the default branch, ie the master branch. The .readthedocs.yaml file at the root of the enterobase-web directory structure provides the information used by readthedocs to create the help pages, including the version of python to be used to assemble the documents, including the them “html_theme = ‘sphinx_rtd_theme’” that is used to create the help pages.

Editing and making the helpfiles on Windows

In Windows it is possible to make a clone of the Enterobase repository using TortoiseGIT and then modify and add help files locally and then submit the changes as a single commit. In order to modify and compile them Python should be installed on the PC, the easiest option being the Python App from windows store. The ‘Sphinx’,’sphinx-rtd-theme’ should be installed (rtd = readTheDocs) .rst files can be editted with a text editor, but the Python ReText editor provides some help with the editor, and the ability to see roughly what the text will look like after it has been compiled.

More detailed info on how to setup a windows PC to be able to edit .rst files using ReText can be found here:

It is possible to check that the files will look OK when transferred to read the docs by doing a local compile using the make.bat file. The command is ‘make html’ and the output html files can be viewed in the _build directory

Editing and making the helpfiles on Unix or MACs

We have not managed to find a way of editting the files using ReText but they can be editted using a text editor. They can then be compiled to give formatted files using Make.bat in a python environment that includes the libraries specified in rtd.requirements.txt. It is probably that this lists more libraries than are really needed for a compilation.

Indexes and appearance of pages

With the sphinx_rtd theme that is used a page will only appear in the index if it is listed in a toc field within another document . Indexes can be nested with the top level index being generated by the index.rst file

References to pages and figures

References to documents and paragraphs are described here:

A reference to a paragraph is written   :ref:`Tree Data`   which appears as Tree Data

A reference to a help page is written   :doc:`/features/metadata-fields`   or   :doc:`Custom title </features/metadata-fields>`   which then appear as Metadata Fields and Custom title

Images and Figures can be included as described here The figure directive is a more advanced version of the image directive. Paths can be relative or absolute. Some examples include:


Tables can be created using the list_table directive, as described here: This also allows tables to be created from external csv files. It is possible to have multiple lines of text in one cell by making them separate paragraphs

which displays like this:

description name param
SeroPred Serotype Prediction



“params”:{“taxon”:”Escherichia”}, “display”:”public”,

“js_grid”:”BaseExperimentGrid”, “summary”:”O”}”

Note that the * that prefixes the begining of each row in the table must line up with the first : in the :list-table parameters

An alternative, conceptually simpler way of doing this is as follows:

Which then appears as:

tabname name mlst_field display_order
SeroPred O log,O 1
SeroPred H log,H 2

Note that all vertical lines must line up and the formatting characters are significant when checking for alignment. The column spacing and formatting within the squares is automatic and ignores white space in the source text.