docs/getting_started/docs-build.rst

   1 Building Documentation
   2 ======================
   3
   4 To create a rendered copy of this documentation locally you can use the
   5 `Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
   6 pages.
   7
   8 If you are building the documentation for the first time then you will need to
   9 check that you have the required software packages, as described in the
  10 *Prerequisites* section that follows.
  11
  12 .. note::
  13    An online copy of the documentation is available at
  14    https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered
  15    copy without doing a local build.
  16
  17 Prerequisites
  18 -------------
  19
  20 For building a local copy of the |TF-A| documentation you will need, at minimum:
  21
  22 - Python 3 (3.5 or later)
  23 - PlantUML (1.2017.15 or later)
  24
  25 You must also install the Python modules that are specified in the
  26 ``requirements.txt`` file in the root of the ``docs`` directory. These modules
  27 can be installed using ``pip3`` (the Python Package Installer). Passing this
  28 requirements file as an argument to ``pip3`` automatically installs the specific
  29 module versions required by |TF-A|.
  30
  31 An example set of installation commands for Ubuntu 18.04 LTS follows, assuming
  32 that the working directory is ``docs``:
  33
  34 .. code:: shell
  35
  36     sudo apt install python3 python3-pip plantuml
  37     pip3 install [--user] -r requirements.txt
  38
  39 .. note::
  40    Several other modules will be installed as dependencies. Please review
  41    the list to ensure that there will be no conflicts with other modules already
  42    installed in your environment.
  43
  44 Passing the optional ``--user`` argument to ``pip3`` will install the Python
  45 packages only for the current user. Omitting this argument will attempt to
  46 install the packages globally and this will likely require the command to be run
  47 as root or using ``sudo``.
  48
  49 .. note::
  50    More advanced usage instructions for *pip* are beyond the scope of this
  51    document but you can refer to the `pip homepage`_ for detailed guides.
  52
  53 Building rendered documentation
  54 -------------------------------
  55
  56 From the ``docs`` directory of the project, run the following commands. It is
  57 important to note that you will not get the correct result if the commands are
  58 run from the project root directory, as that would invoke the top-level Makefile
  59 for |TF-A| itself.
  60
  61 .. code:: shell
  62
  63    make clean
  64    make html
  65
  66 Output from the build process will be placed in:
  67
  68 ::
  69
  70    <tf-a root>/docs/build/html/
  71
  72 --------------
  73
  74 *Copyright (c) 2019, Arm Limited. All rights reserved.*
  75
  76 .. _Sphinx: http://www.sphinx-doc.org/en/master/
  77 .. _pip homepage: https://pip.pypa.io/en/stable/