= Building Documentation = [[TOC(Docs/Build , depth=2)]] This page explains how to build the documentation from source. The documentation can be found in the [https://git.rtems.org/rtems-docs RTEMS Documentation Repository]. It contains [https://git.rtems.org/rtems-docs/tree/README.txt README.txt] and we suggest you also check it for the latest build instructions including host specific details. == Prerequisites == You will need: * [http://www.sphinx-doc.org/ Sphinx] - The Sphinx documentation system. * [https://www.tug.org/texlive/ Tex Live] - The Tex Live document production system. * [https://github.com/remy/inliner Inliner] - Single HTML Page Generator. These tools may be provided by your host's packaging system or you may decide to install them manually. The Tex Live system packaging may result in some fragility on your host system. It depends on how many and how the Tex Live packages are packaged for your host. If in doubt select the '''full''' install. The RTEMS PDF output uses the ''lato'' and ''inconsolata'' fonts. These are not available on some hosts. If the configure phase of the build reports an error related to these Tex packages you can optionally disable support for them resulting in a lower quality documentation. == Sphinx == '''Note:''' Version 1.3 is the minimum version of Sphinx required and version 1.48 is recommended. We have found using a git release can have errors so we suggest avoiding it. Windows users can find detailed instructions on the [http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx Sphinx Website]. Most UNIX distributions have a package for Sphinx. For manual installation refer to the [http://www.sphinx-doc.org/en/stable/install.html Install Page] on the Sphinx website. {{{ $ pip install -U sphinx }}} If you need to update `pip` use: {{{ $ pip install --upgrade --user pip }}} You need to add into your your local copy of Sphinx: {{{ export PATH=${HOME}/.local/bin:${PATH} }}} == Tex Live == To install the Tex Live system from the upstream site run as root: {{{ # cd /somewhere/temporary # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz # tar xf install-tl-unx.tar.gz # cd install-tl-20161106 # ./install-tl }}} NOTE: The date in the name of the directory will change. - Use the command line system. Select `O` for options if you want to change from A4 to US letter paper size by default. - Select `I` to install - The tools will be installed into a directory like the following: /usr/local/texlive/2016/bin/i386-linux/. You will need to have a look to find the exact path. Set the path to the install Tex Live system, make sure it is in front of other system paths: {{{ export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH} }}} == Single HTML == The documentation can be built as a single HTML. This is a compact easy to reference way to view the documentation with some limitations: - No searching. - Section numbering is flat and does not match the HTML or PDF numbering. Install the Node.js package manager for your platform. On FreeBSD the command is: {{{ # pkg install npm }}} Once `npm` is installed install the Inliner package: {{{ # npm install -g inliner }}} == Getting Source == The source is located at: * https://git.rtems.org/rtems-docs.git {{{ $ cd $ mkdir -p development/rtems/docs $ cd development/rtems/docs $ git clone git:://git.rtems.org/rtems-docs.git $ cd rtems-docs }}} == Building == You can build all document from the top level directory or you and enter a specific documents directory and build just that document. for the top level build: {{{ $ ./waf configure $ ./waf build }}} This will build the default `html` output which is a number of HTML files plus searching. The output will in the `build` directory under the manual's names and `html`. You can add a `prefix` to the configure phase to install the output to the prefix: {{{ $ ./waf configure --prefix=/opt/rtems/4.11 $ ./waf build install }}} === Single HTML Output === A single HTML page can be built if the Inliner package is install by adding `--singlehtml` to the `configure` phase: {{{ $ ./waf configure --singlehtml $ ./waf build }}} === PDF Output === PDF format output can be built is Tex Live and `pdflatex` is install by adding `--pdf` to the `configure` phase: {{{ $ ./waf configure --pdf $ ./waf build }}} === All Output Formats === You can build all output formats at once by: {{{ $ ./waf configure --prefix=/opt/rtems/4.11 --singlehtml --pdf $ ./waf build install }}} === Sphinx Warnings === To see the Sphinx warnings use the `--sphinx-verbose=` option. Refer to the Sphinx documentation for the available options. The simplest is to add `-v`, for example: {{{ $ ./waf configure --sphinx-verbose=-v $ ./waf build }}} === PDF Fonts === If your host does not provide the extra fonts we use for a better quality output you can override the configure phase and fall back to use lower quality fonts by adding: {{{ $ ./waf configure --disable-extra-fonts $ ./waf build }}} If the fonts are found on your host the option is ignored.