Documentation

Introduction

All the documentation of BioExcel Building Blocks is available in Read the Docs, a software documentation hosting platform where the source code is freely available, and the service is also free to use. It generates documentation that is written with the Sphinx documentation generator.

All the documentation of BioBBs is written in reStructuredText and Markdown:

reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation.
Markdown is a lightweight markup language with plain-text-formatting syntax. Its design allows it to be converted to many output formats.

The documentation of a BioBB package is divided into four parts:

Introduction and installation

https://biobb-template.readthedocs.io/en/latest/readme.html

README.md file written in Markdown language that is a copy of the main README.md file of the BioBB package. The README.md source code of de biobb_template documentation is located in:

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/readme.md

API documentation

https://biobb-template.readthedocs.io/en/latest/modules.html

This section contains all the documentation related to the source code of the different modules of a BioBB package.

In order to easy the process of documentation, the BioExcel Building Blocks use the sphinx autodoc extension that generates automatically all the documentation related to the source code respecting a certain format for the comments explained below in this same section.

Command Line Documentation

https://biobb-template.readthedocs.io/en/latest/command_line.html

This file is written in Markdown, and contains all the command line instructions. The command_line.md source code of de biobb_template documentation is located in:

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/command_line.md

This file is automatically generated by the Command Line Generator Tool.

Change Log

https://biobb-template.readthedocs.io/en/latest/change_log.html

This file is written in Markdown, and contains the main changes implemented in each new release. The change_log.md source code of de biobb_template documentation is located in:

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/change_log.md

Click here to access to the index page documentation of the biobb_template.

Files structure

init.py files

As explained in the Files structure section, there are two __init__.py files:

biobb_template/biobb_template/__init__.py: define the package name (biobb_template), all the modules contained in this package -only one in this example (template)- and the package version.

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/__init__.py

name = "biobb_template"
__all__ = ["template"]
__version__ = "4.1.0"

biobb_template/biobb_template/template/__init__.py: define the folder name (template) and all the tools contained in this folder, only two in this example (template and template_container).

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/__init__.py

name = "template"
__all__ = ["template", "template_container"]

This two files are used by the sphinx autodoc extension for parsing the directories structure of our BioBB. Therefore, it’s very important to define them properly and put only the modules / tools we want to documentate automatically.

docs folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs

The structure of the docs folder is as follows:

docs/
- source/
  - _static/
  - change_log.md
  - command_line.md
  - conf.py
  - index.rst
  - modules.rst
  - readme.md
  - schema.html
  - template.rst
- Makefile
- requirements.txt

source folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source

This folder contains all the files needed by the sphinx autodoc extension for the creation of the documentation in Read the Docs.

_static/ folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source/_static

This folder contains media related to the documentation:

bioexcel_logo.png: image logo of the BioExcel Project
logo.png: BioExcel Building Blocks image logo
theme_overrides.css: styles file for customising Read the Docs documentation
theme_overrides.js: JavaScript file for customising Read the Docs documentation

change_log.md

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/change_log.md

Change log file in Markdown.

command_line.md

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/command_line.md

Command line file in Markdown created automatically generated by the Command Line Generator Tool

conf.py

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/conf.py

Read the Docs configuration file.

index.rst

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/index.rst

Documentation index file written in reStructuredText:

.. image:: https://bioexcel.eu/wp-content/uploads/2019/04/Bioexcell_logo_1080px_transp.png

BIOBB_TEMPLATE
--------------

Contents
========

.. toctree::
   :maxdepth: 1

   Introduction & installation <readme>
   API Documentation <modules>
   Command Line Documentation <command_line>
   Changelog <change_log>

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

`Github repository <https://github.com/bioexcel/biobb_template>`_.
===================================================================

.. raw:: html
    :file: schema.html

modules.rst

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/modules.rst

Modules section index file written in reStructuredText:

biobb_template
==============

.. toctree::
   :maxdepth: 4

   template

readme.md

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/readme.md

README.md file written in Markdown language that is a copy of the main README.md file of the BioBB package.

schema.html

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/schema.html

Package description file (written in HTML) following the rules of schema.org and more specifically of bioschemas.org.

template.rst

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/template.rst

Template section index file written in reStructuredText. This file is an index of the Python files that must be parsed by the sphinx autodoc extension:

template package
=====================

Submodules
----------

template.template module
------------------------

.. automodule:: template.template
    :members:
    :undoc-members:
    :show-inheritance:

template.template_container module
----------------------------------

.. automodule:: template.template_container
    :members:
    :undoc-members:
    :show-inheritance:

Makefile

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/Makefile

Makefile for Sphinx documentation

requirements.txt

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/requirements.txt

Read the Docs dependencies.

Formats in code comments

As explained before, in order to automate the generation of part of the documentation, we must write the comments of our Python code in a specific format. There are two parts of the code where we have to pay special attention: the definition of the arguments just after the class definition and the description of the functions just after defining them.

Arguments

The arguments must be inside a set of triple quotes just after the class definition in the following format:

| biobb_package ToolName
| Short description for the `tool_name <http://tool_name-documentation.org>`_ module in Restructured Text (reST) syntax. Mandatory.
| Long description for the `tool_name <http://tool_name-documentation.org>`_ module in Restructured Text (reST) syntax. Optional.

Args:
    arg_name1 (arg_type): Description for argument 1. File type: input / output. `Sample file <url_to_sample_file1>`_. Accepted formats: format1 (edam:format_XXXX), format2 (edam:format_XXXX), format3 (edam:format_XXXX). 
    arg_name2 (arg_type) (Optional): Description for argument 2. File type: input / output. `Sample file <url_to_sample_file2>`_. Accepted formats: format1 (edam:format_XXXX), format2 (edam:format_XXXX).
    properties (dic):
        * **property1** (*prop_type*) - (property1_default) [min-max|step] [WF property] Property 1 description. Values: value1 (description for value1), value2 (description for value2), value3 (description for value3).
        * **property2** (*prop_type*) - (property2_default) Property 2 description. 
        * **property3** (*dic*) - (None) Property 3 description.
            * **parameter1** (*param_type*) - (parameter1_default) Parameter 1 description. Values: value1 (description for value1), value2 (description for value2), value3 (description for value3).

Examples:
    This is a use example of how to use the building block from Python::

        from biobb_package.tool_name.tool_name import tool_name

        prop = { 
            'some_boolean_property': True 
        }
        tool_name(arg_name1='/path/to/arg_name1.file',
                  arg_name2='/path/to/arg_name2.file',
                  properties=prop)

Info:
    * wrapped_software:
        * name: Wrapped Software
        * version: >=3.0
        * license: GNU 
    * ontology:
        * name: EDAM
        * schema: http://edamontology.org/EDAM.owl

As seen in the Template class:

class Template():
    """
    | biobb_template Template
    | Short description for the `template <http://templatedocumentation.org>`_ module in Restructured Text (reST) syntax. Mandatory.
    | Long description for the `template <http://templatedocumentation.org>`_ module in Restructured Text (reST) syntax. Optional.

    Args:        
        input_file_path1 (str): Description for the first input file path. File type: input. `Sample file <https://urlto.sample>`_. Accepted formats: top (edam:format_3881).
        input_file_path2 (str) (Optional): Description for the second input file path (optional). File type: input. `Sample file <https://urlto.sample>`_. Accepted formats: dcd (edam:format_3878).
        output_file_path (str): Description for the output file path. File type: output. `Sample file <https://urlto.sample>`_. Accepted formats: zip (edam:format_3987).
        properties (dic):
            * **boolean_property** (*bool*) - (True) Example of boolean property.
            * **binary_path** (*str*) - ("zip") Example of executable binary property.
            * **remove_tmp** (*bool*) - (True) [WF property] Remove temporal files.
            * **restart** (*bool*) - (False) [WF property] Do not execute if output files exist.

    Examples:
        This is a use example of how to use the building block from Python::

            from biobb_template.template.template import template

            prop = { 
                'boolean_property': True 
            }
            template(input_file_path1='/path/to/myTopology.top',
                    output_file_path='/path/to/newCompressedFile.zip',
                    input_file_path2='/path/to/mytrajectory.dcd',
                    properties=prop)

    Info:
        * wrapped_software:
            * name: Zip
            * version: >=3.0
            * license: BSD 3-Clause
        * ontology:
            * name: EDAM
            * schema: http://edamontology.org/EDAM.owl

    """

The docstrings syntax is broadly explained in the JSON Generator help of the utils_biobb repository. Following accurately this syntax, the JSON Generator Tool will automatically generate the JSON Schemas of the package.

Documentation created from the code above:

https://biobb-template.readthedocs.io/en/latest/template.html#template.template.Template

Functions

All the multiline comments inside a set of triple quotes just after the function definition will be used as the function description:

def launch(self) -> int:
    """Execute the :class:`Template <template.template.Template>` object."""