# Documentation

## Introduction

All the documentation of **BioExcel Building Blocks** is available in [Read the Docs](https://readthedocs.org/), 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](https://www.sphinx-doc.org/en/master/).

All the documentation of **BioBBs** is written in [**reStructuredText**](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html) and [**Markdown**](https://www.markdownguide.org/basic-syntax/):

* **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](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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source)

### API documentation

[https://biobb-template.readthedocs.io/en/latest/modules.html](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](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) 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](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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source)

This file is automatically generated by the [Command Line Generator Tool](https://github.com/bioexcel/utils_biobb/tree/master/utils_biobb/command_line).

### Change Log

[https://biobb-template.readthedocs.io/en/latest/change_log.html](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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source)

[Click here](https://biobb-template.readthedocs.io/en/latest/index.html) to access to the index page documentation of the *biobb_template*.

## Files structure

### \_\_init\_\_.py files

As explained in the [Files structure](https://biobb-documentation.readthedocs.io/en/latest/files_structure.html#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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/__init__.py)


```python
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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/__init__.py)


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

This two files are used by the [sphinx autodoc extension](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) 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](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](https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source)

This folder contains all the files needed by the [sphinx autodoc extension](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) for the creation of the documentation in [Read the Docs](https://readthedocs.org/).

##### _static/ folder

[https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source/_static](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](https://bioexcel.eu/)
* 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](https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source)

Change log file in **Markdown**.

##### command_line.md

[https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/command_line.md](https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source)

Command line file in **Markdown** created automatically generated by the [**Command Line Generator Tool**](https://github.com/bioexcel/utils_biobb/tree/master/utils_biobb/command_line)

##### conf.py

[https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/conf.py](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/conf.py)

[Read the Docs](https://readthedocs.org/) configuration file.

##### index.rst

[https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/index.rst](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/index.rst)

Documentation index file written in **reStructuredText**:

```rst
.. 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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/modules.rst)

Modules section index file written in **reStructuredText**:

```rst
biobb_template
==============

.. toctree::
   :maxdepth: 4

   template
```

##### readme.md

[https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/readme.md](https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs/source)

**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](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**](https://schema.org/) and more specifically of [**bioschemas.org**](https://bioschemas.org/).

##### template.rst

[https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/source/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](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html):

```rst
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](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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/docs/requirements.txt)

[Read the Docs](https://readthedocs.org/) 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:

```rst
| 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](https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/template.py) class:


```python
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.
            * **sandbox_path** (*str*) - ("./") [WF property] Parent path to the sandbox directory.

    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](https://github.com/bioexcel/utils_biobb/tree/master/utils_biobb/json#docs-specifications) of the [utils_biobb](https://github.com/bioexcel/utils_biobb) repository. Following accurately this syntax, the [JSON Generator Tool](https://github.com/bioexcel/utils_biobb/blob/master/utils_biobb/json/json_generator.py) 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](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:


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

Documentation created from the code above:

[https://biobb-template.readthedocs.io/en/latest/template.html#template.template.Template.launch](https://biobb-template.readthedocs.io/en/latest/template.html#template.template.Template.launch)