Changes between Version 6 and Version 7 of Docs/Build


Ignore:
Timestamp:
11/09/16 23:56:18 (7 years ago)
Author:
Chris Johns
Comment:

Updated after we have an active rtems-docs.git repo.

Legend:

Unmodified
Added
Removed
Modified

  • Docs/Build

    v6 v7  
    1 = Build Documentation =
     1= Building Documentation =
    22
    33[[TOC(Docs/Build , depth=2)]]
    44
    5 This page explains how to build the documentation from source.
     5This page explains how to build the documentation from source.
     6
     7The 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.
    68
    79== Prerequisites ==
    … …  
    911You will need:
    1012
    11   * [https://www.waf.io/ waf] - The waf build system.
    1213  * [http://www.sphinx-doc.org/ Sphinx] - The Sphinx documentation system.
     14  * [https://www.tug.org/texlive/ Tex Live] - The Tex Live document production system.
     15  * [https://github.com/remy/inliner Inliner] - Single HTML Page Generator.
    1316
    14 === Extras ===
    15 These dependencies are not required by default but are used for other targets.
     17These tools may be provided by your host's packaging system or you may decide to install them manually.
    1618
    17 ||= Target =||= Dependency =||
    18 ||pdf||TeX (pdflatex)||
    19 ||htmlsingle||Node [https://github.com/remy/inliner inliner]||
     19The 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.
    2020
    21 
     21The 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.
    2222
    2323== Sphinx ==
    2424
    25 '''Note:''' Version 1.3 is the minimum version of Sphinx required.
     25'''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.
     26
     27Windows users can find detailed instructions on the [http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx Sphinx Website].
    2628
    2729Most 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.
    2830
    29 Windows users can find detailed instructions on the [http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx Sphinx Website].
     31{{{
     32 $ pip install -U sphinx
     33}}}
     34
     35If you need to update `pip` use:
     36
     37{{{
     38$ pip install --upgrade --user pip
     39}}}
     40
     41You need to add into your your local copy of Sphinx:
     42
     43{{{
     44export PATH=${HOME}/.local/bin:${PATH}
     45}}}
     46
     47== Tex Live ==
     48
     49To install the Tex Live system from the upstream site run as root:
     50
     51{{{
     52# cd /somewhere/temporary
     53# wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
     54# tar xf install-tl-unx.tar.gz
     55# cd install-tl-20161106
     56# ./install-tl
     57}}}
     58
     59NOTE: The date in the name of the directory will change.
     60- Use the command line system. Select `O` for options if you want to
     61  change from A4 to US letter paper size by default.
     62- Select `I` to install
     63- The tools will be installed into a directory like the following:
     64  /usr/local/texlive/2016/bin/i386-linux/. You will need to have a
     65  look to find the exact path.
     66
     67Set the path to the install Tex Live system, make sure it is in front of other system paths:
     68
     69{{{
     70export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
     71}}}
     72
     73== Single HTML ==
     74
     75The documentation can be built as a single HTML. This is a compact easy to reference way to view the documentation with some limitations:
     76
     77- No searching.
     78
     79- Section numbering is flat and does not match the HTML or PDF numbering.
     80
     81Install the Node.js package manager for your platform. On FreeBSD the command is:
     82
     83{{{
     84# pkg install npm
     85}}}
     86
     87Once `npm` is installed install the Inliner package:
     88
     89{{{
     90# npm install -g inliner
     91}}}
    3092
    3193== Getting Source ==
    … …  
    3597  * https://git.rtems.org/rtems-docs.git
    3698
     99{{{
     100$ cd
     101$ mkdir -p development/rtems/docs
     102$ cd development/rtems/docs
     103$ git clone git:://git.rtems.org/rtems-docs.git
     104$ cd rtems-docs
     105}}}
     106
    37107== Building ==
    38108
    39 Each document can be built on its own by entering the directory and typing:
     109You 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:
    40110
    41111{{{
    42   # waf configure
    43   # waf build
     112$ ./waf configure
     113$ ./waf build
    44114}}}
    45115
    46 This will build the default `html` target which is several split files.
     116This 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`.
    47117
    48 === Targets ===
     118You can add a `prefix` to the configure phase to install the output to the prefix:
    49119
    50 ||= Target =||= Result =||
    51 ||--pdf||Build PDF||
    52 ||--htmlsingle||Build a Single HTML file||
     120{{{
     121$ ./waf configure --prefix=/opt/rtems/4.11
     122$ ./waf build install
     123}}}
    53124
     125=== Single HTML Output ===
    54126
     127A single HTML page can be built if the Inliner package is install by adding `--singlehtml` to the `configure` phase:
    55128
     129{{{
     130$ ./waf configure --singlehtml
     131$ ./waf build
     132}}}
    56133
     134=== PDF Output ===
    57135
     136PDF format output can be built is Tex Live and `pdflatex` is install by adding `--pdf` to the `configure` phase:
     137
     138{{{
     139$ ./waf configure --pdf
     140$ ./waf build
     141}}}
     142
     143=== All Output Formats ===
     144
     145You can build all output formats at once by:
     146
     147{{{
     148$ ./waf configure --prefix=/opt/rtems/4.11 --singlehtml --pdf
     149$ ./waf build install
     150}}}
     151
     152=== Sphinx Warnings ===
     153
     154To 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:
     155
     156{{{
     157$ ./waf configure --sphinx-verbose=-v
     158$ ./waf build
     159}}}
     160
     161=== PDF Fonts ===
     162
     163If 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:
     164
     165{{{
     166$ ./waf configure --disable-extra-fonts
     167$ ./waf build
     168}}}
     169
     170If the fonts are found on your host the option is ignored.
     171
     172== ReST Coding Standard ==
     173
     174We have a coding standard for how we use ReST. It is important we use this standard. The standard is documented in [https://git.rtems.org/rtems-docs/tree/README.txt README.txt].