Asking for help

iota2’s documentation is constantly evolving, but not as quickly as the code. If the documentation is unclear or insufficient, or if there is any doubt, you can open an issue on framagit in order to ask the question directly.

The search function allows you to query the questions already asked or dealt with.

Creating a new issue

If iota2 shows a suspicious behavior or you don’t understand why there is a problem you can open a bug issue on framagit.

For the developers to help you, pleas provide the archive present in the iota2 logs directory. It contains most of the information useful for the development team to identify the problem. If it doesn’t appear in the logs directory, report it when opening the issue.

It is also possible to copy/paste the terminal outputs directly into an issue by adding the code tags. To create a code block, click three times on the insert code button and insert your code after the first three code symbols.

Print from terminal or code source

Contribute to documentation

You can contribute to the documentation of iota2, by creating an issue to report a problem or by creating a merge request on framagit.

To contribute to the ‘master’ version of the documentation, you have to make the merge request from the master branch of iota2.

To contribute to the develop version of the documentation, the merge request must be made from the develop branch of iota2.

Once the modifications are made, they will be validated and integrated by the developers and put online as soon as possible. You will then become an official contributor of iota2.

Documentation have two kinds of sources:

  • Generated automatically from source code

  • Manually written

Automated documentation

The API is generated by sphinx using docstrings in the source code. To update this documentation, it is necessary to identify the corresponding python file and then modify the corresponding docstring.

The modification will be automatically done in the online documentation, after compilation, once merged in develop or master.

The parameter tables are written automatically on pre-push events. To update this page, it is necessary to update only the iota2/iota2/configuration_files/ file. In this file, each configuration parameter is a class, and each class has some attributes used in documentation.

Also some text files are generated using pre-push events. All these files (except for API ones) have a note at the beginning indicating that is a file automatically produced and it must not be edited. All changes directly on these rst files will be lost.

Hand written documentation

To edit documentation page like this one, the user must edit the corresponding rst file directly. All documentation files are located in iota2/doc/source/.

To identify which file must be edited, there are two solutions:

  1. From contents.rst, iterate on open corresponding file.

  2. From online documentation, look at the name of the page. For instance, this page is ‘contribute_to_iota2.html’ then the rst file for editing is ‘contribute_to_iota2.rst’

Ask for features

If you are interested in the development of iota2 you can follow the issues on framagit.

You can also participate in open issues, to share your experience on iota2 or to give advice on the use of options for example.

You can also submit new feature ideas that would be useful to iota2 by creating a dedicated issue.

If you wish to integrate one of your ideas into the channel, report it in the created issue, you will receive as much help as necessary to make the addition a success.