Build RTEMS Documentation

The RTEMS Documentation Suite viewable at ​https://docs.rtems.org is built using the ​Sphinx toolset which supports the ​reStructuredText mark up format. The source for the RTEMS Documentation is maintained in git just like the RTEMS Source Code.

Task Description

Download the source code for the RTEMS documentation by using git clone as follows:

git clone git://git.rtems.org/rtems-docs.git

Follow the instructions in the file README.txt in the top of the rtems-docs source tree. It provides guidance on installing the needed tools on various host operating systems. It does not include guidance for as many hosts as the instructions for building RTEMS do. A critical part of this task is helping the RTEMS Project improve these instructions.

Another purpose of this task is to enable you to be able to modify the documentation in subsequent tasks and submit changes. The GCI/Coding/HelloWorld task includes guidance on using git that will be helpful here.

Edit a page in the Users Guide and produce a PDF file of that document. Submit that PDF along with a patch as proof.

Remember that an important part of this task is making the process of building the documentation easier for the next person. Suggest improvements to the README.txt, give us information on host operating systems that are not included, etc..

Feedback

Student Nickname	Sphinx version	Host OS	Feedback
NAME	VERSION	HOST	TBD
zehata	sphinx-build 1.8.2	Ubuntu 18.04	The process was very simple and I only had to use the ./waf configure and ./waf commands and the process was very straightforward. However, to build the pdf file, I had to reinstall tlmgr to update to the 2018 version. Furthermore, LaTeX called multiple errors, which suggests some of the LaTeX files have some error in formatting. To workaround this, use the -kk command when running ./waf (It flags for try extra hard -> I'm not kidding check ./waf --help). So what you want to do is ./waf configure --pdf , install the missing packages, then run ./waf --pdf -kk and this should (hopefully) create the appropriate pdfs. Good luck!

Directions for Mentors

Verify the patch, screenshot, and read the feedback above.

Please file tickets when a host's instructions need updating for packages.