optee_docs

This is the Git where all official OP-TEE documentation resides and this is what you are reading right now. Here we will give instructions on how to write and build the documentation as well as give some guidelines on what to do and not to do. Note that the documentation is written for Sphinx. So, even though GitHub for example renders *.rst files somewhat OK, that is still not the preferred way to read and view the documentation. Instead head over to https://optee.readthedocs.io where the final output is stored and nicely rendered using Sphinx.

Install Sphinx

Before doing anything else, first install Sphinx and the dependencies.

$ sudo apt install graphviz python3-sphinx python3-sphinx-rtd-theme

Build optee_docs

$ git clone https://github.com/OP-TEE/optee_docs
$ cd optee_docs
$ make html

After this step all documentation should have been built and you can open <optee_docs>/_build/html/index.html in your browser to see the result and browse the documentation.

Hint

By using a Linux tool called entr. You can automatically rebuild the pages your are working with. First get the package $ sudo apt install entr, then:

$ cd <optee_docs>
$ find . -name "*.rst" | entr -c make html

With this, entr will automatically rebuild the documentation everytime you make change and save a file. Which means you only have to save the file in your editor and refresh the browser page to see the changes locally.

General guidelines

Linking

rst files

The rst files should have descriptive names, but even more important is where you decide to put the files. Even though it’s not a problem to move files around, we have to remember that we tend to quite often give links to documentation from at GitHub, emails etc. If we move files, there is a high likelihood that they will become dead links in the future (404’s). So think twice before adding a new file or moving an existing file.

Sections, chapters

We have adopted the Sphinx recommended way of using sections, chapters, subsections etc, those are:

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • “, for paragraphs