Docs: Abstract documentation generation into a new file
Abstract the introduction of documentation generation into
a new file.
Signed-off-by: Summer Qin <summer.qin@arm.com>
Change-Id: I0a47e21b426dbb53e8165d08c81e9174958cf6d0
diff --git a/docs/technical_references/instructions/documentation_generation.rst b/docs/technical_references/instructions/documentation_generation.rst
new file mode 100644
index 0000000..29032be
--- /dev/null
+++ b/docs/technical_references/instructions/documentation_generation.rst
@@ -0,0 +1,232 @@
+########################
+Documentation generation
+########################
+
+The build system is prepared to support generation of two documents:
+
+- Reference Manual. Doxygen based.
+- User Guide. Sphinx based.
+
+Both documents can be generated in HTML and PDF format.
+
+Support for document generation in the build environment is not mandatory.
+Missing document generation tools will not block building the TF-M firmware.
+
+***************************
+Build TF-M Reference Manual
+***************************
+
+The following tools are needed:
+
+ - Doxygen v1.8.0 or later
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+ - LaTeX - for PDF generation only
+ - PdfLaTeX - for PDF generation only
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ 1. Set-up the needed tools and environment:
+
+ .. code-block:: bash
+
+ sudo apt-get install -y doxygen graphviz default-jre
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
+ # For PDF generation
+ sudo apt-get install -y doxygen-latex
+
+ 2. Currently, there are two ways of building TF-M reference manual:
+
+ - Using the CMake build system as custom targets
+
+ .. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
+
+ The documentation files will be available under the directory ``cmake_doc/docs/reference_manual``.
+
+ - Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)
+
+ .. code-block:: bash
+
+ # Build the documentation from build_docs directory
+ cd <TF-M base folder>
+ mkdir build_docs
+ cp docs/conf.py build_docs/conf.py
+ cd build_docs
+ sphinx-build ./ user_guide
+
+ # Build the documentation from a custom location
+ # setting the build_docs as input
+
+ # Note that using this method will still generate the reference manual
+ # to the <TF-M base folder>/build_docs/reference_manual
+ cd <TF-M base folder>/<OTHER_DIR>/<OTHER_DIR2>
+ sphinx-build <TF-M base folder>/build_docs/ <DESIRED_OUTPUT_DIR>
+
+ .. Note::
+
+ Invoking Sphinx-build will build both user_guide and
+ reference_manual targets.
+
+ .. group-tab:: Windows
+
+ 1. Download and install the following tools:
+
+ - `Doxygen 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the Arm DS installation or can be
+ downloaded from `here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+ - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
+
+ 2. Set the environment variables, assuming that:
+
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from Arm DS installation.
+
+ .. code-block:: bash
+
+ set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
+ set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
+
+ 3. Using the CMake build system as custom targets to build TF-M
+ reference manual:
+
+ .. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
+
+ The documentation files will be available under the directory ``cmake_doc\docs\reference_manual``.
+
+*********************
+Build TF-M User Guide
+*********************
+
+The following tools are needed:
+
+ - Python3 and the following modules:
+ - Sphinx v1.7.9
+ - m2r v0.2.0
+ - sphinxcontrib-plantuml
+ - sphinxcontrib-svg2pdfconverter
+ - sphinx-rtd-theme
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment 1.8 or later (for running PlantUML)
+ - LaTeX - for PDF generation only
+ - PdfLaTeX - for PDF generation only
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ 1. Set-up the tools and environment:
+
+ .. code-block:: bash
+
+ sudo apt-get install -y python3 graphviz default-jre
+ pip install -r tools/requirements.txt
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+ # For PDF generation
+ sudo apt-get install -y doxygen-latex
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
+ 2. Currently, there are two ways of building TF-M user guide:
+
+ - Using the CMake build system as custom targets
+
+ .. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
+
+ The documentation files will be available under the directory ``cmake_doc/docs/user_guide``.
+
+ - Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)
+
+ .. code-block:: bash
+
+ # Build the documentation from build_docs directory
+ cd <TF-M base folder>
+ mkdir build_docs
+ cp docs/conf.py build_docs/conf.py
+ cd build_docs
+ sphinx-build ./ user_guide
+
+ # Build the documentation from a custom location
+ # setting the build_docs as input
+
+ # Note that using this method will still generate the reference manual
+ # to the <TF-M base folder>/build_docs/reference_manual
+ cd <TF-M base folder>/<OTHER_DIR>/<OTHER_DIR2>
+ sphinx-build <TF-M base folder>/build_docs/ <DESIRED_OUTPUT_DIR>
+
+ .. Note::
+
+ Invoking Sphinx-build will build both user_guide and
+ reference_manual targets.
+
+ .. group-tab:: Windows
+
+ 1. Download and install the following tools:
+
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the Arm DS installation or can be `downloaded from here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+ - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
+ - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
+ - The necessary Python3 packages are listed in the requirements.txt file.
+
+ To install all needed packages just do:
+
+ .. code-block:: bash
+
+ pip install -r tools\requirements.txt
+
+ .. Note::
+ When building the documentation the first time, MikTeX might prompt
+ for installing missing LaTeX components. Please allow the MikTeX
+ package manager to set-up these.
+
+ 2. Set the environment variables, assuming that:
+
+ - plantuml.jar is available at c:\\plantuml\\plantuml.jar
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from DS5 installation.
+
+ .. code-block:: bash
+
+ set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
+ set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
+
+ 3. Using the CMake build system as custom targets to build TF-M user
+ guide:
+
+ .. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
+ cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
+
+ The documentation files will be available under the directory ``cmake_doc\docs\user_guide``.
+
+.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+.. _Doxygen: https://www.doxygen.nl
+
+--------------
+
+*Copyright (c) 2017-2021, Arm Limited. All rights reserved.*