diff options
author | Galanakis, Minos <minos.galanakis@arm.com> | 2019-11-08 11:28:40 +0000 |
---|---|---|
committer | Tamas Ban <tamas.ban@arm.com> | 2019-11-26 11:04:04 +0000 |
commit | 0c1ad78607c2e4e1b764c52f4d42fb7d74d6151e (patch) | |
tree | 44f0ad743bf79dac9fdd876c0a21b33e479b95f4 | |
parent | 6ccf7ec77cc98612c4ba807c5502c19b47e71162 (diff) | |
download | trusted-firmware-m-0c1ad78607c2e4e1b764c52f4d42fb7d74d6151e.tar.gz |
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>
-rw-r--r-- | cmake/Common/BuildSphinxDoc.cmake | 6 | ||||
-rw-r--r-- | cmake/SphinxCopyDoc.cmake | 11 | ||||
-rw-r--r-- | cmake/SphinxDesignDocStatus.cmake | 9 | ||||
-rw-r--r-- | docs/about/coding_guide.rst (renamed from docs/coding_guide.rst) | 5 | ||||
-rw-r--r-- | docs/about/dco.rst (renamed from docs/dco.rst) | 0 | ||||
-rw-r--r-- | docs/about/index.rst | 13 | ||||
-rw-r--r-- | docs/about/maintainers.rst (renamed from docs/maintainers.rst) | 2 | ||||
-rw-r--r-- | docs/design_documents/index.rst.in | 30 | ||||
-rw-r--r-- | docs/index.rst | 55 | ||||
-rw-r--r-- | docs/index.rst.in | 109 | ||||
-rw-r--r-- | docs/processes/contributing.rst (renamed from docs/contributing.rst) | 13 | ||||
-rw-r--r-- | docs/processes/index.rst | 13 | ||||
-rw-r--r-- | docs/readme.rst | 4 | ||||
-rw-r--r-- | docs/user_guides/index.rst | 14 | ||||
-rw-r--r-- | docs/user_guides/services/index.rst | 12 |
15 files changed, 168 insertions, 128 deletions
diff --git a/cmake/Common/BuildSphinxDoc.cmake b/cmake/Common/BuildSphinxDoc.cmake index 74ead011b9..3aea00fef5 100644 --- a/cmake/Common/BuildSphinxDoc.cmake +++ b/cmake/Common/BuildSphinxDoc.cmake @@ -76,9 +76,10 @@ if (NOT SPHINX_NODOC) 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 @@ if (NOT SPHINX_NODOC) 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 e95757c739..6bf2f073ad 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 @@ endforeach() #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 e76c448a6c..88438d3406 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 @@ function(sphinx_configure_index) #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 index aefb2b7b11..87c49c77e3 100644 --- a/docs/coding_guide.rst +++ b/docs/about/coding_guide.rst @@ -18,8 +18,9 @@ remain within clear scope. 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 index 7a5a4c3255..7a5a4c3255 100644 --- a/docs/dco.rst +++ b/docs/about/dco.rst diff --git a/docs/about/index.rst b/docs/about/index.rst new file mode 100644 index 0000000000..d872bfa498 --- /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 index e7736d4812..468ed82df5 100644 --- a/docs/maintainers.rst +++ b/docs/about/maintainers.rst @@ -6,7 +6,7 @@ be approved and merged by the maintainers listed below. 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 0000000000..b5cf149af8 --- /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 0000000000..5ada82456e --- /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 f891cf560d..0000000000 --- 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 index 8cc9e40a76..321d4be4be 100644 --- a/docs/contributing.rst +++ b/docs/processes/contributing.rst @@ -5,7 +5,8 @@ Contributions to the TF-M project need to follow the process below. .. 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 @@ Contributions to the TF-M project need to follow the process below. <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 @@ Contributions to the TF-M project need to follow the process below. 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 0000000000..d3e453eff8 --- /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 a36dc83fc9..e771bf087b 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -19,7 +19,7 @@ License ####### 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 @@ To port TF-M to a another system or OS, follow the 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 0000000000..79bdc5d458 --- /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 0000000000..94aec92a58 --- /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.* |