Doc: Added nested index structure
This patch adjusts the structure of documentation, making it
easier to organise and navigate.
* Modifies index.rst.in decoupled from cmake index.rst.
* Creates respective indexes in the documentation sub-directories
and links them to the master index
* External component documentation is preserved
* CMAKE build system is updated to automate the document listing
in the design_documents index instead of the master index.
Change-Id: I697b68e19dc57ecf7f36bc6dd8248fe345bdad61
Signed-off-by: Galanakis, Minos <minos.galanakis@arm.com>
diff --git a/cmake/Common/BuildSphinxDoc.cmake b/cmake/Common/BuildSphinxDoc.cmake
index 74ead01..3aea00f 100644
--- a/cmake/Common/BuildSphinxDoc.cmake
+++ b/cmake/Common/BuildSphinxDoc.cmake
@@ -76,9 +76,10 @@
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in")
set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/conf.py")
- set(SPHINX_TEMPLATE_INDEX_FILE "${TFM_ROOT_DIR}/docs/index.rst.in")
- set(SPHINX_CONFIGURED_INDEX_FILE "${SPHINX_TMP_DOC_DIR}/index.rst")
set(SPHINX_DESIGN_DOC_ROOT "${TFM_ROOT_DIR}/docs/design_documents")
+ set(SPHINX_TEMPLATE_INDEX_FILE "${SPHINX_DESIGN_DOC_ROOT}/index.rst.in")
+ set(SPHINX_CONFIGURED_INDEX_FILE "${SPHINX_TMP_DOC_DIR}/docs/design_documents/index.rst")
+ set(SPHINX_MAIN_INDEX_FILE "docs/index.rst")
#Version ID of TF-M.
#TODO: this shall not be hard-coded here. We need a process to define the
@@ -111,6 +112,7 @@
COMMAND "${CMAKE_COMMAND}" -D TFM_ROOT_DIR=${TFM_ROOT_DIR}
-D DST_DIR=${SPHINX_TMP_DOC_DIR}
-D BINARY_DIR=${CMAKE_BINARY_DIR}
+ -D MASTER_IDX=${SPHINX_MAIN_INDEX_FILE}
-P "${TFM_ROOT_DIR}/cmake/SphinxCopyDoc.cmake"
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
DEPENDS run-allways
diff --git a/cmake/SphinxCopyDoc.cmake b/cmake/SphinxCopyDoc.cmake
index e95757c..6bf2f07 100644
--- a/cmake/SphinxCopyDoc.cmake
+++ b/cmake/SphinxCopyDoc.cmake
@@ -26,10 +26,11 @@
#
#Usage:
# cmake -DDST_DIR=<path to destination> -DTFM_ROOT_DIR=<path to tf-m root> \
-# -DBINARY_DIR=${CMAKE_BINARY_DIR} -P SphinxCopyDoc.cmake
+# -DBINARY_DIR=${CMAKE_BINARY_DIR}
+# -DMASTER_IDX=<path to master index.rst> -P SphinxCopyDoc.cmake
#Check input parameters
-foreach(_PARAM IN ITEMS TFM_ROOT_DIR DST_DIR BINARY_DIR)
+foreach(_PARAM IN ITEMS TFM_ROOT_DIR DST_DIR BINARY_DIR MASTER_IDX)
if (NOT DEFINED ${_PARAM})
message(FATAL_ERROR "Variable ${_PARAM} is undefined. Please add -D${_PARAM}=<...> when calling this script.")
endif()
@@ -56,5 +57,9 @@
#Copy files with directory tree.
foreach(_FILE ${_COPY_FILES})
get_filename_component(_DIR ${_FILE} DIRECTORY)
- file(COPY ${_FILE} DESTINATION "${DST_DIR}/${_DIR}")
+ if (_FILE STREQUAL MASTER_IDX)
+ file(COPY ${_FILE} DESTINATION "${DST_DIR}")
+ else()
+ file(COPY ${_FILE} DESTINATION "${DST_DIR}/${_DIR}")
+ endif()
endforeach()
diff --git a/cmake/SphinxDesignDocStatus.cmake b/cmake/SphinxDesignDocStatus.cmake
index e76c448..88438d3 100644
--- a/cmake/SphinxDesignDocStatus.cmake
+++ b/cmake/SphinxDesignDocStatus.cmake
@@ -20,7 +20,7 @@
Include(CMakeParseArguments)
#This function will search for .rst files in a given directory, read them and
-#check if the :Status: field is defined in them. Then will add each file to a
+#check if the ":Status:" field is defined in them. Then will add each file to a
#list with a name matching the status value.
#See the definition of _STATE_VALUES below for a list of valid state values.
#Files with missing or invalid state value will be placed on the "unknown" list.
@@ -174,15 +174,16 @@
#Loop over files on the list of this status
foreach(_FILE IN LISTS _DD_${_STATUS})
- #Get the path of the file relative to the document root
- file(RELATIVE_PATH _REL_FILE ${_MY_PARAMS_DOC_ROOT} ${_FILE})
+
+ # Strip path from the filesince index is placed in same location
+ get_filename_component(_FILE ${_FILE} NAME)
#Detailed and Draft files go to the same section
if (_STATUS STREQUAL "DETAILED")
set(_STATUS "DRAFT")
endif()
#Append the file to the output string
- string(APPEND ${_STATUS}_DD_LIST "\n ${_REL_FILE}")
+ string(APPEND ${_STATUS}_DD_LIST "\n ${_FILE}")
endforeach()
endforeach()
diff --git a/docs/coding_guide.rst b/docs/about/coding_guide.rst
similarity index 95%
rename from docs/coding_guide.rst
rename to docs/about/coding_guide.rst
index aefb2b7..87c49c7 100644
--- a/docs/coding_guide.rst
+++ b/docs/about/coding_guide.rst
@@ -18,8 +18,9 @@
The guidance below is provided as a help. It isn't meant to be a definitive
list.
-As implied in the :doc:`contributing guide </docs/contributing>` maintainers
-have the right to decide on what's acceptable in case of any divergence.
+As implied in the :doc:`contributing guide </docs/processes/contributing>`
+maintainers have the right to decide on what's acceptable in case of any
+divergence.
.. Warning::
diff --git a/docs/dco.rst b/docs/about/dco.rst
similarity index 100%
rename from docs/dco.rst
rename to docs/about/dco.rst
diff --git a/docs/about/index.rst b/docs/about/index.rst
new file mode 100644
index 0000000..d872bfa
--- /dev/null
+++ b/docs/about/index.rst
@@ -0,0 +1,13 @@
+About
+=====
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/maintainers.rst b/docs/about/maintainers.rst
similarity index 96%
rename from docs/maintainers.rst
rename to docs/about/maintainers.rst
index e7736d4..468ed82 100644
--- a/docs/maintainers.rst
+++ b/docs/about/maintainers.rst
@@ -6,7 +6,7 @@
Sub-maintainers' approval is required for their specific areas of ownership.
Contributions must follow the instructions in
-:doc:`Contributing Guidelines </docs/contributing>`.
+:doc:`Contributing Guidelines </docs/processes/contributing>`.
Maintainers
-----------
diff --git a/docs/design_documents/index.rst.in b/docs/design_documents/index.rst.in
new file mode 100644
index 0000000..b5cf149
--- /dev/null
+++ b/docs/design_documents/index.rst.in
@@ -0,0 +1,30 @@
+Design Documents
+================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Accepted design documents
+ :glob:
+ :numbered:
+
+ @ACCEPTED_DD_LIST@
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Draft design documents
+ :glob:
+ :numbered:
+
+ @DRAFT_DD_LIST@
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Rejected design documents
+ :glob:
+ :numbered:
+
+ @REJECTED_DD_LIST@
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..5ada824
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,55 @@
+:Page authors: Gyorgy Szing <gyorgy.szing@arm.com>
+
+..
+ The build-system will copy all documents into a temporary directory tree
+ before the documentation is built.
+ This file will be copied to the top level and thus please use relative paths
+ as if this file would be in <TFM_ROOT_DIR>.
+
+ The values between @ characters will be filled in by CMake.
+
+
+Trusted Firmware-M Documentation
+================================
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ Home<docs/readme>
+ docs/about/index
+ docs/design_documents/index
+ docs/user_guides/index
+ docs/processes/index
+ docs/glossary
+ docs/lic
+
+.. toctree::
+ :caption: Components
+ :maxdepth: 2
+ :glob:
+ :hidden:
+
+ lib/**
+
+.. toctree::
+ :caption: Target platforms
+ :maxdepth: 2
+ :glob:
+ :hidden:
+
+ platform/**
+
+.. toctree::
+ :caption: Tools
+ :maxdepth: 2
+ :glob:
+ :hidden:
+
+ tools/iat-verifier/*
+
+.. include:: docs/readme.rst
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst.in b/docs/index.rst.in
deleted file mode 100644
index f891cf5..0000000
--- a/docs/index.rst.in
+++ /dev/null
@@ -1,109 +0,0 @@
-:Page authors: Gyorgy Szing <gyorgy.szing@arm.com>
-
-..
- The build-system will copy all documents into a temporary directory tree
- before the documentation is built.
- This file will be copied to the top level and thus please use relative paths
- as if this file would be in <TFM_ROOT_DIR>.
-
- The values between @ characters will be filled in by CMake.
-
-
-Trusted Firmware-M Documentation
-================================
-
-.. toctree::
- :maxdepth: 2
- :hidden:
-
- Home<docs/readme>
- docs/lic
- docs/dco
- docs/maintainers
- docs/glossary
- docs/contributing
- docs/user_guides/tfm_sw_requirement
- docs/user_guides/tfm_build_instruction
- docs/user_guides/tfm_user_guide
- docs/user_guides/tfm_integration_guide
- docs/coding_guide
-
-.. toctree::
- :maxdepth: 2
- :caption: Guides Contd
- :hidden:
-
- docs/user_guides/os_migration_guide_armv8m
- docs/user_guides/tfm_ns_client_identification
- docs/user_guides/tfm_secure_boot
- docs/user_guides/tfm_secure_irq_handling
-
-.. toctree::
- :caption: Processes
- :maxdepth: 2
- :glob:
- :hidden:
-
- docs/processes/**
-
-.. toctree::
- :caption: Secure services
- :maxdepth: 2
- :glob:
- :hidden:
-
- docs/user_guides/services/*
-
-.. toctree::
- :caption: Components
- :maxdepth: 2
- :glob:
- :hidden:
-
- lib/**
-
-.. toctree::
- :caption: Target platforms
- :maxdepth: 2
- :glob:
- :hidden:
-
- platform/**
-
-.. toctree::
- :caption: Design documents
- :maxdepth: 2
- :glob:
- :hidden:
-
- @ACCEPTED_DD_LIST@
-
-.. toctree::
- :caption: Draft design documents
- :maxdepth: 2
- :glob:
- :hidden:
-
- @DRAFT_DD_LIST@
-
-.. toctree::
- :caption: Rejected design documents
- :maxdepth: 2
- :glob:
- :hidden:
-
- @REJECTED_DD_LIST@
-
-.. toctree::
- :caption: Tools
- :maxdepth: 2
- :glob:
- :hidden:
-
- tools/iat-verifier/*
-
-.. include:: docs/readme.rst
-
------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/contributing.rst b/docs/processes/contributing.rst
similarity index 85%
rename from docs/contributing.rst
rename to docs/processes/contributing.rst
index 8cc9e40..321d4be 100644
--- a/docs/contributing.rst
+++ b/docs/processes/contributing.rst
@@ -5,7 +5,8 @@
.. Note::
- Please contact :doc:`maintainers </docs/maintainers>` for any questions.
+ Please contact :doc:`maintainers </docs/about/maintainers>` for any
+ questions.
- Subscribe to `TF-M development
<https://lists.trustedfirmware.org/mailman/listinfo/tf-m>`_ if not subscribed
@@ -27,14 +28,15 @@
<http://git.trustedfirmware.org/trusted-firmware-m.git>`_.
- Follow the :doc:`SW Requirements </docs/user_guides/tfm_sw_requirement>`,
:doc:`Build Instructions </docs/user_guides/tfm_build_instruction>` and
- :doc:`Coding Guide </docs/coding_guide>` for the TF-M project.
+ :doc:`Coding Guide </docs/about/coding_guide>` for the TF-M project.
- Make your changes in logical chunks to help reviewers. Each commit should
be a separate review and either work properly or be squashed after the
review and before merging.
- Update documentation in docs/ folder if needed.
- Test your changes and add details to the commit description.
- - The code is accepted under :doc:`DCO </docs/dco>`, Developer Certificate of
- Origin, so you must add following fields to your commit description:
+ - The code is accepted under :doc:`DCO </docs/about/dco>`, Developer
+ Certificate of Origin, so you must add following fields to your
+ commit description:
.. code-block:: text
@@ -53,7 +55,8 @@
git push ssh://review.trustedfirmware.org:29418/trusted-firmware-m.git HEAD:refs/for/master
-- Add relevant :doc:`maintainers </docs/maintainers>` for reviewing the patch.
+- Add relevant :doc:`maintainers </docs/about/maintainers>` for reviewing
+ the patch.
- You may be asked to provide further details or make additional changes.
- You can discuss further with maintainer(s) by directly over email if
necessary.
diff --git a/docs/processes/index.rst b/docs/processes/index.rst
new file mode 100644
index 0000000..d3e453e
--- /dev/null
+++ b/docs/processes/index.rst
@@ -0,0 +1,13 @@
+Processes
+=========
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/readme.rst b/docs/readme.rst
index a36dc83..e771bf0 100644
--- a/docs/readme.rst
+++ b/docs/readme.rst
@@ -19,7 +19,7 @@
#######
The software is provided under a BSD-3-Clause :doc:`License </docs/lic>`.
Contributions to this project are accepted under the same license with developer
-sign-off as described in the :doc:`Contributing Guidelines </docs/contributing>`.
+sign-off as described in the :doc:`Contributing Guidelines </docs/processes/contributing>`.
This project contains code from other projects as listed below. The code from
external projects is limited to ``app`` and ``platform`` folders.
@@ -120,7 +120,7 @@
Please also see the :doc:`glossary </docs/glossary>` of terms used in the project.
-:doc:`Contributing Guidelines </docs/contributing>` contains guidance on how to
+:doc:`Contributing Guidelines </docs/processes/contributing>` contains guidance on how to
contribute to this project.
Further documents can be found in the ``docs`` folder.
diff --git a/docs/user_guides/index.rst b/docs/user_guides/index.rst
new file mode 100644
index 0000000..79bdc5d
--- /dev/null
+++ b/docs/user_guides/index.rst
@@ -0,0 +1,14 @@
+User Guides
+===========
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+ services/index
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/index.rst b/docs/user_guides/services/index.rst
new file mode 100644
index 0000000..94aec92
--- /dev/null
+++ b/docs/user_guides/services/index.rst
@@ -0,0 +1,12 @@
+Services
+========
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*