Home

Welcome to the sw-docs wiki! In this webpage you can find some guidelines about how to contribute or how to write documentation.

Documentation Guidelines

The software documentation included in readthedocs writen in reStructured Text (RST). It is an easy to read markup syntax, designed for extensibility. In addition, we use Sphinx, a tool that makes easier to create visual and beautiful documentation. A useful guide about how to use Sphinx (and sublime) can be found here.

IC Cities Documentation

Whenever a new city is included in IC, its documentation has to be added in the readthedocs. It should be an extension of the small description included in the code:

As a template/example, Irene (readthedocs, code) can be used. In the Workflow section, the maximum amount of the details are expected (including drawings, and plots). Addition details about this can be found in doc-db (back-up slides).

PDF format

The readthedocs the documentation can be read in PDF format. You should check that any change should be readable also there. Open the webpage in your browser and click in the 'latest' option in the corner left. Afterwards, in Downloads section follow the pdf link.

How to contribute

This repository, as the others in next-exp, follow a specific git workflow. More information about it, can be found on readthedocs-workflow. Whenever some new documentation want to be added into the main repository, a PR should be created about it.

Test your documentation in your local machine

When contributing to documentation, you can check your read-the-docs status in your local computer before pushing the changes to the local branch. In order to do so, you need to have sphinx installed, together with an extension (sphinx-autodoc-typehints) and the sphinx theme (sphinx_rtd_theme). The three of them can be instaled by pip install. Afterwards, you can run

$ make html

in the sw-docs/docs/ directory. You can check your documentation in your browser typing:

file:///path_to_repository/sw-docs/docs/build/html/index.html

NOTE: It is recommended to check the html using incognito mode in your browser. Otherwise, cookies need to be erased everytime a new change is added.

Contribute with your documentation

Whenever a new Pull Request (PR) is added in this repository, a read-the-docs link should created to simplify the review. Read-the-docs links are created signing in on the readthedocs-webpage with your GitHub account:

• import a new project from the forked repository (user_name/sw-docs):

  

  

• be sure you are using the PR branch, and name the readthedocs using the following name prXXX-sw-docs.readthedocs.io where XXX corresponds to the number of the PR

  

IMPORTANT: Project should be erased once the PR is approved.

Reviewer Guidelines

Are you reviewieng any part of the documentation? These are the guidelines you have to follow when doing any type of review.

Review check list

• Check the readthedocs link provided in the PR, not only the documentation code.
• Check that content in PR fits accordingly in the PDF format of the readthedocs: tables, figures, etc.
• Units are defined with math format (:math:)
• Figures do not include caption, but they need to be mentioned in the text, either before or after they are inserted.
• Check that all the links pointing to other parts of the documentation, or outside the readthedocs, are pointing correctly.
• For IC cities:
  • All configuration parameters for each city need to be described in the config section.
  • All configuration parameters need to mentioned along the workflow description of the city.
  • Whenever another city is mentioned, it is referenced using :doc:name_city