Documentation ¶

Documentation is written using Sphinx, a python documentation system built using reStructuredText (ReST; .rst). The docs configuration contains both ReST files that contain pages in the documentation and configuration files for Sphinx.

The Sphinx website also contains plenty of documentation details concerning ReST markup and working with Sphinx in general.

Organization ¶

The documentation folder BacterialTyper/docs/source organization is distributed in multifple files, folders and subfolders:

api - Placeholders to automatically generate the application programming interface (API) documentation.
devel - Developers guidelines to contribute to the project.
faq - Frequently asked questions (FAQs).
glossary - Glosary entries and abreviations.
images - Images to include in the documentation.
tutorial - Tutorial examples for the BacterialTyper modules.
user_guide - The user guide and documentation to interpret results and analysis.
index.rst - The top level index document for the documentation.
conf.py - Sphinx configuration parameters.
Makefile and make.bat - Entry points for building the docs.
_static - Used by the sphinx build system.
_templates - Used by the sphinx build system.

The .rst files are kept in user_guide, devel, api, glossary and tutorial.

The main entry point is index.rst, which contains links for users guide, developers guide, api reference, and FAQs. The documentation suite is built as a single document in order to make the most effective use of cross referencing.

There are also .rst files that are contained in api/modules and api/scripts that are automatically generated from the docstrings of the functions in BacterialTyper scripts and main modules. These sources consist of python scripts that have ReST documentation built into their comments. See section API Docstrings for details.

Build the docs ¶

Instructions to build the documentation for developer purposes.

All documentation is built from the BacterialTyper/docs/ directory.

We will follow the rules for the documentation generated for the Matplotlib documentation configuration.

Installing dependencies ¶

Attention

You will need a minimal working LaTeX distribution.

To build the docs, you will need to install several python modules because documentation is generated from reStructuredText (ReST) using the Sphinx documentation generation tool.

There are several extra python requirements that are needed to build the documentation. They are listed in docs/config/doc-requirements.txt, which is shown below:

sphinx==7.1.2
sphinxmark==1.0.0
rinohtype==0.5.4
sphinxcontrib-bibtex==2.6.1

You will need a BacterialTyper (and dependencies) working distribution included in your $PYTHONPATH (activate your virtual environment as mentioned here) and then additionally install documentation requirements using pip.

pip install docs/config/doc-requirements.txt

Also, there is a perl module required for the documentation generation. It is called latexmk and it should be available if you have a working LaTeX installation.

See additional details here:

latexmk,http://mirrors.ctan.org/support/latexmk.zip

We encourage to install this module using CPAN (https://www.cpan.org/) or any other perl package installer of your interest.

Finally, in order to generate the python graph dependency images, the tool graphviz and an specific python module is required.

The python module pyan needs to be installed using pip from github. See https://github.com/ttylec/pyan for additional details. Type:

pip install git+https://github.com/ttylec/pyan

To install graphviz type and other LaTeX dependencies, check file docs/config/system-requirements.sh

sudo apt install texlive-full
sudo apt install texmaker
sudo apt install graphviz

sh docs/config/system-requirements.sh

Building documentation ¶

The documentation sources are found in the docs/source directory in the trunk. The configuration file for Sphinx is docs/source/conf.py. It controls which directories Sphinx parses, how the docs are built, and how the extensions are used.

To build the documentation in html format, cd into docs/source/ and run:

make html

To delete built files. It may help if you get errors about missing paths or broken links.

make clean

To generate a pdf file of the documentation.

make latexpdf

Writing ReST pages ¶

Most documentation is either in the docstring of individual classes and methods, in explicit .rst files, or in examples and tutorials.

All of these use the reStructuredText (ReST) syntax. Users should look at the ReST documentation for a full description. But some hints and conventions uses are describing as a quickstart for creating documentation.

Section headers ¶

Section headers are created by underlining the section title with a punctuation character, at least as long as the text:

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python’s Style Guide for documenting which you may follow:

“#” with overline, for parts

“*” with overline, for chapters

“=” for sections

“-” for subsections

“^” for subsubsections

‘”’ for paragraphs

Referring to other documents and sections ¶

Sphinx allows internal references between documents.

Documents can be linked with the :doc: directive:

See the :doc:`../../../info/info_index`

See the installation user guide :doc:`../../../user_guide/installation/installing`

will render as:

See the Additional information

See the installation user guide Installation

Sections can also be given reference names and be referenced using the :ref: directive.

For instance, see here an example from the assemble link:

.. _assembly-workflow:

Workflow
--------

The assemble module contains several main functions (See :doc:`assemble module <../../api/modules/assemble>` for additional details.)
Below we show the workflow of the assembly process.

and refer to it using the standard reference syntax:

See :ref:`assembly-workflow`

will give the following link: Workflow

Note

To maximize internal consistency in section labeling and references, use hyphen separated, descriptive labels for section references. Since underscores are widely used by Sphinx itself, use hyphens to separate words.

Include hyperlinks ¶

To include an hyperlink in a word just type:

Example: `Google <https://www.google.com>`_.

and this will create the following:

Example: Google

Include citations ¶

The bibliography is included BibTex format in file docs/source/bib/references.bib. The initiation and style of the bibliography is determined by file docs/source/bib/bib_index.rst and the directive .. bibliography::.

To include a citation you will use the role :cite: and the tag associated to each entry.

And example of citation might be:

Whatever text you want to reference :cite:`Deplano2018`.

That will render as:

Whatever text you want to reference [2]

Writing docstrings ¶

Docstrings should conform to the reStructuredText (ReST) syntax guide.

Example docstring ¶

An example docstring looks like:

#!/usr/bin/env python3

def hello_world(fasta_file, name, new_fasta):
    """
    Rename fasta sequences provided in file :file:`fasta_file` using id :file:`name`. 
    Save results in file :file:`new_fasta` provided.

    Check for id character lenght do not exceed 37 characters as it might be a limitiation 
    in further annotation and subsequent analysis. Read Prokka_ issue for further details: 
    https://github.com/tseemann/prokka/issues/337.
    
    :param fasta_file: Absolute path to fasta file.
    :param name: String to add every fasta sequence header.
    :param new_fasta: Name for the new fasta file (Absolute path).
    
    :type name: string
    :type fasta_file: string
    :type new_fasta: string
    
    :return: Path to tabular delimited file containing conversion from all to new id for each sequence.
    :warnings: Returns FAIL if name is >37 characters.
    
    .. include:: ../../links.inc

    """
    print("Hello world!")

And it displays like:

hello_world()

Rename fasta sequences provided in file fasta_file using id name. Save results in file new_fasta provided.

Check for id character lenght do not exceed 37 characters as it might be a limitiation in further annotation and subsequent analysis. Read Prokka issue for further details: https://github.com/tseemann/prokka/issues/337.

Parameters:

fasta_file (string) – Absolute path to fasta file.
name (string) – String to add every fasta sequence header.
new_fasta (string) – Name for the new fasta file (Absolute path).

Returns:

Path to tabular delimited file containing conversion from all to new id for each sequence.

Warnings:

Returns FAIL if name is >37 characters.

For other docstrings example visit https://matplotlib.org/devel/documenting_mpl.html#example-docstring

Check an example for python documentation here: https://thomas-cokelaer.info/tutorials/sphinx/index.html

API Docstrings ¶

Most of the API documentation is written in docstrings. These are comment blocks in source code that explain how the code works. For each module and script available we have to create an .rst file in docs/api directory. Then, using the :automodule: directive and :members: role we automatically include every docstring within the source code available.

Using a shell loop we create an .rst file for each module and script:

modules (file docs/source/devel/documentation/modules_api-docstrings.sh):

#!/usr/bin/env bash

cd BacterialTyper/docs/source/api/modules
for i in `dir ../../../../BacterialTyper/modules`; do 
	name=(${i//.py/}); 
	file=$name".rst"; 
	echo ".. _"$name":" >> $file; 
	echo "" >> $file; 
	echo $name >> $file; 
	echo "========" >> $file; 
	echo ".. automodule:: BacterialTyper.modules."$i >> $file; 
	echo "    :members:" >> $file; 
done;

scripts (file docs/source/devel/documentation/scripts_api-docstrings.sh):

for i in `dir ../../../../BacterialTyper/scripts/`; do name=(${i//.py/}); file=$name".rst"; echo ".. _"$name":" >> $file; echo "" >> $file; echo $name >> $file; echo "==========================================" >> $file; echo "This script contains several functions. Here we show a graph representation of the different functions and relationships among them:" >> $file; echo "" >> $file; echo ".. image:: ../../images/python_graph/"$name".png" >> $file; echo "    :align: center" >> $file; echo "" >> $file; echo ".. automodule:: BacterialTyper.scripts."$name >> $file; echo "    :members:" >> $file; echo "    :undoc-members:" >> $file; echo "" >> $file; echo ".. include:: ../../links.inc" >> $file;  done

Python Graph images ¶

Additionally, for each script or module of interest, we generate a graph representation of the different functions and relationships with other modules.

Images are stored in docs/source/images/python_graph. We also include automatically these images generated for the corresponding .rst file using the previous shell script.

To generate the python graph image, we would employ the python module pyan and the graphviz tool. See https://github.com/ttylec/pyan for additional details.