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 https://readthedocs.org/dashboard/ with the username WarwickBioinformaticsRTP, Email address BioinformaticsRTP@warwick.ac.uk for managing the automatic generation of help pages at https://enterobase.readthedocs.io/en/latest/index.html
The Enterobase project has been setup to create web pages from the ‘latest’ commit to the repository at https://bitbucket.org/enterobase/enterobase-web 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: https://warwick.ac.uk/research/rtp/bioinformatics/aboutus/dyer/software/retext_on_windows/
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: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html
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 https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html The figure directive is a more advanced version of the image directive. Paths can be relative or absolute. Some examples include:
Tables¶
Tables can be created using the list_table directive, as described here: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html. 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 | {“input_type”:”assembly”,”pipeline”:”SeroPred”, “query_method”:”process_generic_query”, “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.