fix(docs): add support for readthedocs
- Remove cmake variables from conf.py.in and rename it to confy.py
- Remove dependency on package plantuml
- Move tools/requirements.txt to docs
- Scale down image cca_software_arch.png
These changes make documentation build compatible when built using
cmake or readthedocs.
Signed-off-by: Arunachalam Ganapathy <arunachalam.ganapathy@arm.com>
Change-Id: I4331e6a435b25d1c50439ac85e396737d8042feb
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 9f43b03..0e3f1a6 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -10,20 +10,18 @@
find_package(Python3)
find_package(Sphinx)
find_package(PythonModules COMPONENTS sphinx-rtd-theme sphinxcontrib.plantuml)
-find_package(PlantUML)
+find_package(Git)
set(SPHINXCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/user_guide)
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
+if (SPHINX_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML AND GIT_FOUND)
-if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
-
- file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
+ file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR} *.rst conf.py)
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
- COMMAND "${SPHINX_EXECUTABLE}" -W -b html "${CMAKE_CURRENT_SOURCE_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html" -c ${CMAKE_CURRENT_BINARY_DIR}
- WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+ COMMAND "${SPHINX_EXECUTABLE}" -W -b html "${CMAKE_CURRENT_SOURCE_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
+ WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}/docs"
DEPENDS ${SPHINXCFG_DOC_FILES}
)
add_custom_target(rmm_docs_userguide_html
diff --git a/docs/about/diagrams/cca_software_arch.png b/docs/about/diagrams/cca_software_arch.png
index bff8fa2..e0f117d 100644
--- a/docs/about/diagrams/cca_software_arch.png
+++ b/docs/about/diagrams/cca_software_arch.png
Binary files differ
diff --git a/docs/conf.py.in b/docs/conf.py
similarity index 80%
rename from docs/conf.py.in
rename to docs/conf.py
index 58e3426..248b9c0 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py
@@ -7,11 +7,8 @@
# See the options documentation at http://www.sphinx-doc.org/en/master/config
import os
-
-RMM_ROOT_DIR = "@CMAKE_SOURCE_DIR@"
-PLANTUML_JAR_PATH = "@PLANTUML_JAR_PATH@"
-Java_JAVA_EXECUTABLE = "@Java_JAVA_EXECUTABLE@"
-SPHINXCFG_RMM_VERSION = "v@CMAKE_PROJECT_VERSION@"
+import re
+from subprocess import check_output
# -- Project information -----------------------------------------------------
@@ -19,7 +16,18 @@
copyright = 'TF-RMM Contributors'
author = 'TF-RMM Contributors'
title = 'User Guide'
-version = SPHINXCFG_RMM_VERSION
+
+try:
+ vregx = re.compile(r'tf-rmm-(?P<GIT_VERSION>v.+?)'
+ r'(-[0-9]+-)?(?P<GIT_SHA>g[a-f0-9]{7,})?$')
+ git_result = check_output("git describe --tags --always",
+ shell = True, encoding = 'UTF-8')
+ _v = vregx.match(git_result)
+ release = _v.group('GIT_VERSION')
+ if _v.group('GIT_SHA'):
+ version = release + "+" + _v.group('GIT_SHA')[:7]
+except:
+ version = 'Unknown'
# -- General configuration ---------------------------------------------------
@@ -28,9 +36,6 @@
# ones.
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml']
-#Location of PlantUML
-plantuml = Java_JAVA_EXECUTABLE + " -jar " + PLANTUML_JAR_PATH
-
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -57,7 +62,7 @@
# Load the contents of the global substitutions file into the 'rst_prolog'
# variable. This ensures that the substitutions are all inserted into each page.
-with open(RMM_ROOT_DIR + '/docs/global_substitutions.txt', 'r') as subs:
+with open('global_substitutions.txt', 'r') as subs:
rst_prolog = subs.read()
# Minimum version of sphinx required
@@ -76,7 +81,7 @@
html_theme = "sphinx_rtd_theme"
# The logo to display in the sidebar
-html_logo = RMM_ROOT_DIR + '/docs/_static/images/TrustedFirmware-Logo_standard-white.png'
+html_logo = '_static/images/TrustedFirmware-Logo_standard-white.png'
# Options for the "sphinx-rtd-theme" theme
html_theme_options = {
@@ -86,10 +91,10 @@
}
# Path to _static directory
-html_static_path = [RMM_ROOT_DIR + '/docs/_static']
+html_static_path = ['_static']
# Path to css file relative to html_static_path
-html_css_files = [RMM_ROOT_DIR + '/docs/_static/css/rmm_custom.css',]
+html_css_files = ['css/rmm_custom.css',]
# -- Options for autosectionlabel --------------------------------------------
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index ce58ea9..ab787a7 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -74,7 +74,6 @@
.. code-block:: bash
- export PLANTUML_JAR_PATH=<install path>/bin/plantuml/plantuml.jar
cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DRMM_DOCS=ON
cmake --build ${RMM_BUILD_DIR} -- docs
diff --git a/docs/getting_started/getting-started.rst b/docs/getting_started/getting-started.rst
index 3f9392f..72889e4 100644
--- a/docs/getting_started/getting-started.rst
+++ b/docs/getting_started/getting-started.rst
@@ -48,8 +48,6 @@
"Git",, "Firmware, Documentation"
"Graphviz dot",">v2.38.0","Documentation"
"docutils",">v2.38.0","Documentation"
- "JRE",">=10.0","Documentation"
- "plantuml",,"Documentation"
.. _getting_started_toolchain:
@@ -107,13 +105,8 @@
.. code:: shell
- sudo apt-get install -y git build-essential python3 python3-pip make ninja-build default-jre
+ sudo apt-get install -y git build-essential python3 python3-pip make ninja-build
sudo snap install cmake
- wget https://github.com/plantuml/plantuml/releases/download/v1.2022.7/plantuml-1.2022.7.jar -P <plantuml install path>
-
-.. note::
-
- platUML and JRE are only required for documentation build.
2. Verify cmake version:
@@ -125,12 +118,11 @@
Please download cmake 3.19 or later version from https://cmake.org/download/.
-3. Add CMake and platUML path into environment:
+3. Add CMake path into environment:
.. code-block:: bash
export PATH=<CMake path>/bin:$PATH
- export PLANTUML_JAR_PATH=<plantuml install path>/plantuml.jar
###########################
Install python dependencies
@@ -141,14 +133,14 @@
The installation of Python dependencies is an optional step. This is required only
if building documentation.
-RMM's ``tools/requirements.txt`` file declares additional Python dependencies.
+RMM's ``docs/requirements.txt`` file declares additional Python dependencies.
Install them with ``pip3``:
.. code-block:: bash
pip3 install --upgrade pip
cd <rmm source folder>
- pip3 install -r tools/requirements.txt
+ pip3 install -r docs/requirements.txt
.. _getting_started_get_source:
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..b208795
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,10 @@
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Copyright TF-RMM Contributors.
+#
+graphviz
+Sphinx>=2.4,<3.0.0
+sphinx-rtd-theme
+sphinxcontrib-plantuml
+docutils==0.16
+jinja2<3.1
diff --git a/tools/requirements.txt b/tools/requirements.txt
deleted file mode 100644
index 4449570..0000000
--- a/tools/requirements.txt
+++ /dev/null
@@ -1,6 +0,0 @@
-graphviz
-Sphinx>=2.4,<3.0.0
-sphinx-rtd-theme
-sphinxcontrib-plantuml
-docutils==0.16
-jinja2<3.1
