How to work with Tango Controls documentation¶
Intended audience: developers
When writing or improving the Tango Controls documentation it is worth to follow these guidelines. This will help in keeping it as consistent as possible. It is also important to know how the contents and the sources are structured to make your effort efficient. You will find necessary information below.
About this documentation¶
The documentation is written with the Sphinx markup language. It is a documentation framework based on Docutils and uses reStructuredText for providing content. For details please refer to Sphinx webpage.
The documentation sources are stored on GitHub: https://github.com/tango-controls/tango-doc .
It is publicised in HTML, PDF and EPUB formats on the readthedoc.io: http://tango-controls.readthedocs.io/
Some of the documents were not originally writen in Sphinx. These have been converted from other formats like HTML, LaTeX or Word. These may contain some residual bugs and syntax errors left after conversion. They will be consequently corrected when found.
Updating the documentation¶
If you find that some useful information is missing, misleading or you can think about any potential improvements please do either:
- send a request through the github project: https://github.com/tango-controls/tango-doc/issues
- or do correction by yourself.
If you decide to contribute by writing, the preferred way is to:
- clone or fork the repository,
- create your own local fix branch,
- when finished, send a pull request to the origin/master branch.
Note
GitHub online edit
For small fixes, you may use GitHub online editing feature. It is a good practice to avoid direct commits to ‘dev’ nor to ‘master’ branch. Please select Create a new branch and start pull request before sending the change.
For details see Documentation workflow tutorial.
Building/previewing documentation locally¶
To build the documentation you will need Sphinx environment which is a Python package. Please consult Sphinx webpage for details on how to install it.
Warning
Some standard Python packages contain a buggy version of Breathe. You may need to install it from sources. You may use the following command:
pip install --upgrade git+git://github.com/michaeljones/breathe@cc8f830
After having Sphinx and Breathe installed you will be able to build the documentation:
- go to (cd) folder where you have cloned the repository
- call sphinx-build source build
This will build HTML output in the build
folder.Then you may use any web browser to view the documentation.
Note
The build process generates a lot of warnings. Don’t worry. We will work to remove as much of them as possible but some are inevitable.
For more details and step-by-step guidance pleas refer to Documentation workflow tutorial.
Sources structure¶
Tango Controls versions¶
The readthedocs.io allows to publish various versions of the documentation. It is achieved by providing branches in a git repository. The official version branches are these named numerically as Tango Controls versions: #.#.#.
Chapters and headers¶
Chapters’ order is defined by the main table of contents. It is contained in a file source/contents.rst
and
referenced index.rst files.
To keep chapters levels consistent please use the following underlining schema:
- First level underline: ==== (equal signs)
- Second level: —— (dashes)
- Third level: ~~~ (waves)
References¶
Basic list of Reference Names
is provided within source/conf.py
as a rst_epilog variable. The contents of this variable
is dynamically concatenated to the end of each .rst file during the building process. As of today, it provides some common
hyperlink targets. However, it is planned to include some common substitutions.
The list allows to use some entries like `Tango webpage`_ which will be rendered as Tango webpage
Glossary¶
Glossary entries (definitions) may be provided as content of any document. However, there is
a source/reference/glossary.rst
file. Its purpose is to centralise short definitions of main concepts of Tango Controls.
Entries defined there may be referenced as :term:`…` at any location in the documentation.
Images¶
Fore each document, images should be stored in a sub-folder of the folder where the document is stored. As an example,
please refer to source/tools-and-extensions/astor
. When a folder contains more than one document the images folder should
be named as the document itself. See source/getting-started/installation/tango-on-windows
as an example.
Configuration¶
sources/conf.py¶
This is a standard build configuration file used by Sphinx. Among others the project name, version and copyright info are defined there. Please refer to conf.py documentation.
requirements.txt¶
This is a standard pip requirements file used to fix packages version. Currently it contains Sphinx only.
readthedocs.yml¶
This is a configuration file for the readthedocs application. It provides some fine-grain settings. For Tango Controls it limits output formats to standard HTML, PDF and EPUB. Leaving this setting blank will lead to some problems with the build process at readthedocs.