Contributors Guide¶
Updating the documentation¶
The documentation is build and hosted by a service called Read the docs (rtd) which uses Sphinx to build html, pdf and epub documentation. The process is automated such that any commit to the INTO-CPS Documentation repo causes the documentation to be updated. Sphinx uses a markdown-like format called reStructuredText (rst) which is suitable for creating hierarchical document structures contains cross-references.
Anyone can contribute to the documentation provided they have write access to INTO-CPS Documentation repo.
The documentation shown on this webpage is stored in the Documentation/docs directory as shown below.
Of particular interest is the index.rst and conf.py file, the former being the entry point of the documentation and the latter being the configuration used by Sphinx.
The documentation can be build using the make command in the docs folder.
make html # builds html docs
make latexpdf # builds pdf
make linkcheck # verifies links are correct
A good way to familiarize yourself with the workflow and rst is to go through Read the docs: Getting started with Sphinx. Additionally, there exists a several good references on rst such as Sphinx reStructuredText Primer, Thomas Cokelar rst Cheatsheet , and Ralsina rst Cheatsheet .
Contact¶
The easiest way to get in contact with us is using the INTO-CPS Association Gitter channel or https://into-cps.org/contact/. This is a great place for less formal questions and sharing ideas if you want to contribute.
In case you have encountered an bug in one of the tools, please use the appropriate issue tracker as listed in Issues.
Issues¶
Have you encountered any issues related to the tools? If so these can be submitted to the bug tracker of the respective projects. The majority of these project are hosted on GitHub and makes use of its built-in issue tracker. The remaining use other systems that may require a sign-up in order to view and submit issues.
Below is a list of the issue trackers of the different tools:
- Maestro
- INTO-CPS Desktop Application
- Overture
- 20-sim FMU export
- OpenModelica
- Modelio: general issues and INTO-CPS related issues
- RT-Tester (signup required)
Warning
TODO:
- 20-sim issue tracker appears to no longer exist.
- DSE repo does not exist/”empty repo”
Likewise, if you encounter an error in the documentation, such as a dead link, or you have a suggestion for how to improve the documentation, please submit an issue to the documentation issue tracker