Docs: Decouple from CMAKE and enable sphynx-build.
This patch is reducing the dependency of the documentation to
the TrustedFirmware-M build environment. Currently CMake will
copy over files from platforms, render the configuration files,
sort design documents and invoke the corresponding tools to
build the documentation.
This patch introduces an environment communicating interface file,
which CMAKE will need to populate, before calling the build command.
The file copy operation has been moved over to the sphynx-build logic,
and the design document’s classification is no longer required by the
new user interface.
The new implemenatation allows:
* Documentation can be built in an identical way through the build system,
retaining compatibility with existing tools, such as the CI.
* It is now possible to build documentation, by just invoking sphynx-build
from the build-docs directory.
* Third party tools/services like readthedocs.org can now render
the TF-M documentation.
* Reduced CMake code size.
* Documentation generating logic invokes ‘git describe’ in order to determine
a version. The order of precedence is set as:
Git Describe Version-> CMake hardcoded version -> Template version.
* CMake logic can still toggle parts of the new logic on and off if required.
* The full set of TF-M build dependencies are not longer required in order
to build documentation. Just the documentation dependencies would suffice.
Change-Id: I12e7bbffe9d1adb756329c46da13905e95096381
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/tools/documentation/tfm_copy_files.py b/tools/documentation/tfm_copy_files.py
new file mode 100644
index 0000000..09226c8
--- /dev/null
+++ b/tools/documentation/tfm_copy_files.py
@@ -0,0 +1,87 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2020, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# -----------------------------------------------------------------------------
+
+# Interface module for pre-processing the documentation content
+# before sphynx-build is called
+#
+# It collects files from multiple sources in a intermediate location
+# before calling sphinx-build, thus overriding the limitation
+# of having the documentation share a common root directory.
+#
+# It can be triggered by simply importing the module
+import os
+from shutil import copy2, copytree, rmtree, move
+from glob import glob
+from tfm_cmake_defaults import *
+from subprocess import call
+
+
+def tfm_copy_files():
+ doc_files = []
+
+ # Recursively list all files with extensions and add them
+ for _path in document_scan_dirs:
+ _path = os.path.abspath(os.path.join(tfm_def_root_dir, _path))
+ for ext in document_scan_ext:
+ doc_files.extend([f for f in glob(os.path.join(_path,
+ "**/*%s" % ext),
+ recursive=True)])
+
+ # Add the extra files
+ for _doc_file in documents_extra:
+ _doc_file = os.path.abspath(os.path.join(tfm_def_root_dir, _doc_file))
+ if os.path.isfile(_doc_file):
+ doc_files.append(_doc_file)
+
+ # Clean up all files in target dir except conf.py and tfm_env.py
+ files = [f for f in
+ glob("*", recursive=False) if f not in ["conf.py",
+ tfm_def_conf_out_file,
+ os.path.basename(
+ tfm_def_doxy_output_dir),
+ "tfm_env.py"]]
+ for f in files:
+ if os.path.isfile(f):
+ os.remove(f)
+ elif os.path.isdir(f):
+ rmtree(f)
+
+ # Copy the documentation folder as is
+ copytree(tfm_def_doc_root, tfm_def_copy_doc_root)
+
+ # Move the index to the intermediate build directory
+ # docs/index.rst --> ./index.rst
+ move(os.path.join(tfm_def_copy_doc_root, "index.rst"), tfm_def_copy_dir)
+
+ for df in list(doc_files):
+ # Set the target filename to be cwd + relative to root path of origin
+ target_f = os.path.relpath(df, tfm_def_root_dir)
+ target_f = os.path.join(tfm_def_copy_dir, target_f)
+ # Create path for file (nested) without exception if exists
+ os.makedirs(os.path.dirname(target_f), exist_ok=True)
+ # Copy the file to new location
+ copy2(df, target_f)
+
+
+# Build Doxygen Documnetation
+if tfm_def_build_doxygen:
+ # if conf file is not provided by cmake
+ if tfm_def_render_cmake:
+ render_cmake_file(cmake_env,
+ tfm_def_doxygen_in_file,
+ tfm_def_doxygen_out_file)
+ # Call doxygen to generate the documentation
+ doxygen_bin = find_package("doxygen")
+ call([doxygen_bin, tfm_def_doxygen_out_file])
+
+# Only act if requested by defaults
+if tfm_def_copy_files:
+ tfm_copy_files()
+
+if tfm_def_render_cmake:
+ # Render the conf_py file
+ render_cmake_file(cmake_env, tfm_def_conf_in_file, tfm_def_conf_out_file)