Docs: Restructuring and new layout
This patch implements a set of user-experiences aimed
changes.It modifies the documentation structure and
switches to a more reactive design for the rtd theme.
* The documentation layout has been redesigned to be more
intuitive,easier to maintain and and scale.
* The landing page introduces a new dashboard.
* Introduced dedicated space for release documents, and
changelog has been modified to directly source content
from referenced documents.
* Added quick-link navigation for items that need emphasis.
* Relevant design documents can now be grouped in suf-folders.
* There is dedicated space for custom platform, and third
party tools documents.
* Wildcard and regex matching has been introduced to indexes.
Change-Id: Ib02d17d5d26187d397ba17317788cf2a01401b07
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
deleted file mode 100644
index c50f05c..0000000
--- a/docs/_static/css/custom.css
+++ /dev/null
@@ -1,22 +0,0 @@
-/*
- * Copyright (c) 2019, Arm Limited. All rights reserved.
- *
- * SPDX-License-Identifier: BSD-3-Clause
- *
- */
-
-.wy-nav-content {
- max-width: 85% !important;
-}
-
-/* Avoid tables not wrapping text */
-@media screen and (min-width: 767px) {
-
- .wy-table-responsive table td {
- white-space: normal !important;
- }
-
- .wy-table-responsive {
- overflow: visible !important;
- }
-}
diff --git a/docs/_static/css/tfm_custom.css b/docs/_static/css/tfm_custom.css
new file mode 100644
index 0000000..909e2ac
--- /dev/null
+++ b/docs/_static/css/tfm_custom.css
@@ -0,0 +1,85 @@
+/*-----------------------------------------------------------------------------
+# Copyright (c) 2020, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#----------------------------------------------------------------------------*/
+
+/* Expand width to fill screen */
+.wy-nav-content {
+ max-width: none;
+}
+
+/* Flexbox Tile Grid Settings */
+.grid {
+ list-style-type: none !important;
+ display: -webkit-box;
+ display: -ms-flexbox;
+ display: flex;
+ -ms-flex-wrap: wrap;
+ flex-wrap: wrap;
+ -webkit-box-pack: center;
+ -ms-flex-pack: center;
+ justify-content: center;
+ margin: 1rem auto;
+ max-width: calc((250px + 2rem) * 4);
+}
+
+.grid-item {
+ list-style-type: none !important;
+ -webkit-box-flex: 0;
+ -ms-flex: 0 0 auto;
+ flex: 0 0 auto;
+ width: 220px;
+ text-align: center;
+ margin: 1rem;
+}
+
+.grid-item a {
+ display: block;
+ width: 220px;
+ height: 220px;
+ padding: 22px;
+ display: -webkit-box;
+ display: -ms-flexbox;
+ display: flex;
+ -webkit-box-orient: vertical;
+ -webkit-box-direction: normal;
+ -ms-flex-direction: column;
+ flex-direction: column;
+ -webkit-box-pack: center;
+ -ms-flex-pack: center;
+ justify-content: center;
+ -webkit-box-align: center;
+ -ms-flex-align: center;
+ align-items: center;
+ border: 1px solid #c6cbce;
+ background-color: #2980B9;
+ color: white;
+}
+
+.grid-item h2 {
+ font-size: 1.1rem;
+}
+
+.grid-item img {
+ margin-bottom: 1.1rem;
+ max-width: 75%;
+}
+
+.grid-item a:hover {
+ background-color: #32cd32;
+ color: white;
+}
+
+
+.grid-item p {
+ margin-top: 0.5rem;
+ color: #333e48;
+}
+
+.grid-icon {
+ line-height: 1.8;
+ font-size: 6rem;
+ color: #343131;
+}
diff --git a/docs/_static/images/tfm.png b/docs/_static/images/tfm.png
new file mode 100644
index 0000000..3a8cabf
--- /dev/null
+++ b/docs/_static/images/tfm.png
Binary files differ
diff --git a/docs/about/index.rst b/docs/about/index.rst
deleted file mode 100644
index d872bfa..0000000
--- a/docs/about/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-About
-=====
-.. toctree::
- :maxdepth: 1
- :caption: Contents
- :glob:
- :numbered:
-
- *
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/conf.py.in b/docs/conf.py.in
index 81e1134..f3739be 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py.in
@@ -125,7 +125,7 @@
#Add custom css for HTML. Used to allow full page width rendering
def setup(app):
- app.add_stylesheet('css/custom.css')
+ app.add_stylesheet('css/tfm_custom.css')
# -- Options for HTMLHelp output ---------------------------------------------
diff --git a/docs/about/coding_guide.rst b/docs/contributing/coding_guide.rst
similarity index 95%
rename from docs/about/coding_guide.rst
rename to docs/contributing/coding_guide.rst
index 87c49c7..099d3b3 100644
--- a/docs/about/coding_guide.rst
+++ b/docs/contributing/coding_guide.rst
@@ -18,7 +18,7 @@
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/processes/contributing>`
+As implied in the :doc:`contributing guide </docs/contributing/contributing>`
maintainers have the right to decide on what's acceptable in case of any
divergence.
@@ -76,4 +76,4 @@
--------------
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
diff --git a/docs/processes/contributing.rst b/docs/contributing/contributing.rst
similarity index 79%
rename from docs/processes/contributing.rst
rename to docs/contributing/contributing.rst
index 3708b06..761f52f 100644
--- a/docs/processes/contributing.rst
+++ b/docs/contributing/contributing.rst
@@ -5,7 +5,7 @@
.. Note::
- Please contact :doc:`maintainers </docs/about/maintainers>` for any
+ Please contact :doc:`maintainers </docs/contributing/maintainers>` for any
questions.
- Subscribe to `TF-M development
@@ -19,22 +19,22 @@
<https://developer.trustedfirmware.org/maniphest>`_, put as many details as
possible in the description. Add 'Trusted Firmware M' in the 'Tags' field.
- For non-trivial changes, need to follow the design proposal process
- :doc:`Design Proposal Process </docs/processes/tfm_design_proposal_process>`
+ :doc:`Design Proposal Process </docs/contributing/tfm_design_proposal_process>`
for the TF-M project.
- After the design has been accepted by the maintainer(s), a corresponding
patch should be posted; follow guidelines below:
- Clone the TF-M code on your own machine from `TF-M git repository
<https://git.trustedfirmware.org/TF-M/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/about/coding_guide>` for the TF-M project.
+ - Follow the :doc:`SW Requirements </docs/getting_started/tfm_sw_requirement>`,
+ :doc:`Build Instructions </docs/getting_started/tfm_build_instruction>` and
+ :doc:`Coding Guide </docs/contributing/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/about/dco>`, Developer
+ - The code is accepted under :doc:`DCO </docs/contributing/dco>`, Developer
Certificate of Origin, so you must add following fields to your
commit description:
@@ -55,7 +55,7 @@
git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master
-- Add relevant :doc:`maintainers </docs/about/maintainers>` for reviewing
+- Add relevant :doc:`maintainers </docs/contributing/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
diff --git a/docs/about/dco.rst b/docs/contributing/dco.rst
similarity index 100%
rename from docs/about/dco.rst
rename to docs/contributing/dco.rst
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 0000000..f21a1c7
--- /dev/null
+++ b/docs/contributing/index.rst
@@ -0,0 +1,14 @@
+Contributing
+============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/lic.rst b/docs/contributing/lic.rst
similarity index 100%
rename from docs/lic.rst
rename to docs/contributing/lic.rst
diff --git a/docs/about/maintainers.rst b/docs/contributing/maintainers.rst
similarity index 96%
rename from docs/about/maintainers.rst
rename to docs/contributing/maintainers.rst
index e177952..811035f 100644
--- a/docs/about/maintainers.rst
+++ b/docs/contributing/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/processes/contributing>`.
+:doc:`Contributing Guidelines </docs/contributing/contributing>`.
Main maintainers
----------------
diff --git a/docs/processes/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst
similarity index 96%
rename from docs/processes/tfm_design_proposal_process.rst
rename to docs/contributing/tfm_design_proposal_process.rst
index 4dfcce1..0be4d04 100644
--- a/docs/processes/tfm_design_proposal_process.rst
+++ b/docs/contributing/tfm_design_proposal_process.rst
@@ -69,9 +69,9 @@
available locally. Setting up the documentation tools will allow pre-viewing the
documentation file in preparation.
For information on what tools are needed please refer to
-:doc:`sw requirements </docs/user_guides/tfm_sw_requirement>`. To see how to get
+:doc:`sw requirements </docs/getting_started/tfm_sw_requirement>`. To see how to get
a local copy of the TF-M repository please see
-:doc:`build instructions </docs/user_guides/tfm_build_instruction>`
+:doc:`build instructions </docs/getting_started/tfm_build_instruction>`
Process steps
-------------
diff --git a/docs/design_documents/booting_a_dual_core_system.rst b/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst
similarity index 100%
rename from docs/design_documents/booting_a_dual_core_system.rst
rename to docs/design_documents/dual-cpu/booting_a_dual_core_system.rst
diff --git a/docs/design_documents/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
similarity index 100%
rename from docs/design_documents/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
rename to docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
diff --git a/docs/design_documents/media/dual_core_mailbox_arch.png b/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png
similarity index 100%
rename from docs/design_documents/media/dual_core_mailbox_arch.png
rename to docs/design_documents/dual-cpu/dual_core_mailbox_arch.png
Binary files differ
diff --git a/docs/design_documents/dual-cpu/index.rst b/docs/design_documents/dual-cpu/index.rst
new file mode 100644
index 0000000..f302748
--- /dev/null
+++ b/docs/design_documents/dual-cpu/index.rst
@@ -0,0 +1,12 @@
+Dual-CPU
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/mailbox_design_on_dual_core_system.rst b/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
similarity index 99%
rename from docs/design_documents/mailbox_design_on_dual_core_system.rst
rename to docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
index 45809bc..baa2e71 100644
--- a/docs/design_documents/mailbox_design_on_dual_core_system.rst
+++ b/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst
@@ -86,7 +86,7 @@
The architecture is showed in following figure.
-.. figure:: media/dual_core_mailbox_arch.png
+.. figure:: dual_core_mailbox_arch.png
******************************************
Mailbox communication for PSA Client calls
diff --git a/docs/design_documents/tfm_multi_core_access_check.rst b/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst
similarity index 100%
rename from docs/design_documents/tfm_multi_core_access_check.rst
rename to docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst
diff --git a/docs/design_documents/index.rst b/docs/design_documents/index.rst
new file mode 100644
index 0000000..9f85a76
--- /dev/null
+++ b/docs/design_documents/index.rst
@@ -0,0 +1,15 @@
+Design Documents
+================
+
+.. toctree::
+ :maxdepth: 2
+ :titlesonly:
+ :glob:
+ :numbered:
+
+ */index
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/design_documents/source_structure.rst b/docs/design_documents/source_structure.rst
index 66ca057..b22be0b 100644
--- a/docs/design_documents/source_structure.rst
+++ b/docs/design_documents/source_structure.rst
@@ -6,7 +6,7 @@
:Contact: tf-m@lists.trustedfirmware.org
.. note::
- Refernce the document :doc:`Glossary </docs/glossary>` for terms and
+ Refernce the document :doc:`Glossary </docs/reference/glossary>` for terms and
abbreviations.
************
diff --git a/docs/design_documents/symmetric_initial_attest.rst b/docs/design_documents/symmetric_initial_attest.rst
index 7807fac..a763433 100644
--- a/docs/design_documents/symmetric_initial_attest.rst
+++ b/docs/design_documents/symmetric_initial_attest.rst
@@ -590,7 +590,7 @@
.. [2] :doc:`Trusted Firmware-M Profile Small Design </docs/design_documents/tfm_profile_small>`
-.. [3] :doc:`Initial Attestation Service Integration Guide </docs/user_guides/services/tfm_attestation_integration_guide>`
+.. [3] :doc:`Initial Attestation Service Integration Guide </docs/reference/services/tfm_attestation_integration_guide>`
.. [4] `HMAC: Keyed-Hashing for Message Authentication <https://tools.ietf.org/html/rfc2104>`_
diff --git a/docs/design_documents/tfm_profile_small.rst b/docs/design_documents/tfm_profile_small.rst
index 1353bbf..d427aab 100644
--- a/docs/design_documents/tfm_profile_small.rst
+++ b/docs/design_documents/tfm_profile_small.rst
@@ -703,15 +703,15 @@
.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths <https://www.nist.gov/publications/transitioning-use-cryptographic-algorithms-and-key-lengths>`_
-.. [7] :doc:`ITS integration guide </docs/user_guides/services/tfm_its_integration_guide>`
+.. [7] :doc:`ITS integration guide </docs/reference/services/tfm_its_integration_guide>`
.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Implement/IHI0085-PSA_Attestation_API-1.0.2.pdf?revision=eef78753-c77e-4b24-bcf0-65596213b4c1&la=en&hash=E5E0353D612077AFDCE3F2F3708A50C77A74B2A3>`_
-.. [9] :doc:`Secure boot </docs/user_guides/tfm_secure_boot>`
+.. [9] :doc:`Secure boot </docs/getting_started/tfm_secure_boot>`
.. [10] :doc:`Crypto design </docs/design_documents/tfm_crypto_design>`
-.. [11] :doc:`TF-M build instruction </docs/user_guides/tfm_build_instruction>`
+.. [11] :doc:`TF-M build instruction </docs/getting_started/tfm_build_instruction>`
--------------
diff --git a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
index a0c998e..95a6c82 100644
--- a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
+++ b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst
@@ -28,7 +28,7 @@
.. code-block:: json
- "irqs": [
+ {"irqs": [
{
"line_num": 17,
"signal": "RTC"
@@ -37,7 +37,7 @@
"line_name": "UART1_IRQ",
"signal": "UART1"
}
- ]
+ ]}
Partition ISR function
======================
@@ -227,4 +227,4 @@
- ``irq_signal`` indicates more than one signal.
- ``irq_signal`` is not currently asserted.
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..4b08906
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,13 @@
+Getting Started Guides
+======================
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :glob:
+ :numbered:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/os_migration_guide_armv8m.rst b/docs/getting_started/os_migration_guide_armv8m.rst
similarity index 100%
rename from docs/user_guides/os_migration_guide_armv8m.rst
rename to docs/getting_started/os_migration_guide_armv8m.rst
diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
similarity index 98%
rename from docs/user_guides/tfm_build_instruction.rst
rename to docs/getting_started/tfm_build_instruction.rst
index 9637633..121ef84 100644
--- a/docs/user_guides/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -5,10 +5,10 @@
:doc:`software requirements <tfm_sw_requirement>`.
The external dependecies are briefly listed in the
-:ref:`docs/user_guides/tfm_sw_requirement:External dependencies` section.
+:ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
The configuration-table
-:ref:`docs/user_guides/tfm_build_instruction:Configuring the build` section
+:ref:`docs/getting_started/tfm_build_instruction:Configuring the build` section
explains all the supported build parameters:
****************
@@ -42,7 +42,7 @@
.. Note::
For building with Armclang compiler version 6.10.0, please follow the note
- in :ref:`docs/user_guides/tfm_sw_requirement:External dependencies` section.
+ in :ref:`docs/getting_started/tfm_sw_requirement:External dependencies` section.
.. Note::
For building with the IAR toolchain, please see the notes in
diff --git a/docs/user_guides/tfm_build_instruction_iar.rst b/docs/getting_started/tfm_build_instruction_iar.rst
similarity index 100%
rename from docs/user_guides/tfm_build_instruction_iar.rst
rename to docs/getting_started/tfm_build_instruction_iar.rst
diff --git a/docs/user_guides/tfm_integration_guide.rst b/docs/getting_started/tfm_integration_guide.rst
similarity index 100%
rename from docs/user_guides/tfm_integration_guide.rst
rename to docs/getting_started/tfm_integration_guide.rst
diff --git a/docs/user_guides/tfm_ns_client_identification.rst b/docs/getting_started/tfm_ns_client_identification.rst
similarity index 100%
rename from docs/user_guides/tfm_ns_client_identification.rst
rename to docs/getting_started/tfm_ns_client_identification.rst
diff --git a/docs/user_guides/tfm_secure_boot.rst b/docs/getting_started/tfm_secure_boot.rst
similarity index 100%
rename from docs/user_guides/tfm_secure_boot.rst
rename to docs/getting_started/tfm_secure_boot.rst
diff --git a/docs/user_guides/tfm_secure_irq_handling.rst b/docs/getting_started/tfm_secure_irq_handling.rst
similarity index 100%
rename from docs/user_guides/tfm_secure_irq_handling.rst
rename to docs/getting_started/tfm_secure_irq_handling.rst
diff --git a/docs/user_guides/tfm_sw_requirement.rst b/docs/getting_started/tfm_sw_requirement.rst
similarity index 99%
rename from docs/user_guides/tfm_sw_requirement.rst
rename to docs/getting_started/tfm_sw_requirement.rst
index ca8688e..2c3d555 100644
--- a/docs/user_guides/tfm_sw_requirement.rst
+++ b/docs/getting_started/tfm_sw_requirement.rst
@@ -7,7 +7,7 @@
.. |DEV_STUDIO_VERSION| replace:: 2018.0
A quick reference table is included in the
-:ref:`docs/user_guides/tfm_sw_requirement:Tool & Dependency overview` section
+:ref:`docs/getting_started/tfm_sw_requirement:Tool & Dependency overview` section
of this document.
****************************
diff --git a/docs/user_guides/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst
similarity index 100%
rename from docs/user_guides/tfm_user_guide.rst
rename to docs/getting_started/tfm_user_guide.rst
diff --git a/docs/index.rst b/docs/index.rst
index f360584..06bfdcd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,40 +8,97 @@
The values between @ characters will be filled in by CMake.
-
Trusted Firmware-M Documentation
================================
+.. raw:: html
+
+ <ul class="grid">
+ <li class="grid-item">
+ <a href="docs/introduction/readme.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Introduction</h2>
+ </a>
+ <p>Introducing the Trusted Firmware-M Project: overview,
+ architecture, features, and licensing</p>
+ </li>
+ <li class="grid-item">
+ <a href="docs/getting_started/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Getting Started Guides</h2>
+ </a>
+ <p>Follow this guide to set up a development environment on your
+ system, and then build and run a sample application.</p>
+ </li>
+ <li class="grid-item">
+ <a href="docs/contributing/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Contribution Guidelines</h2>
+ </a>
+ <p>As an open-source project, we welcome and encourage the community
+ to submit patches directly to the project.</p>
+ </li>
+ <li class="grid-item">
+ <a href="docs/reference/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>References</h2>
+ </a>
+ <p>User guides, API Documentation, interfaces</p>
+ </li>
+ <li class="grid-item">
+ <a href="docs/design_documents/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Design</h2>
+ </a>
+ <p>Design documents, threat models.</p>
+ </li>
+ <li class="grid-item">
+ <a href="platform/ext/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>Platforms</h2>
+ </a>
+ <p>List of supported boards and platforms.</p>
+ </li>
+ <li class="grid-item">
+ <a href="https://ci.trustedfirmware.org/job/tf-m-build-docs/lastSuccessfulBuild/artifact/trusted-firmware-m/build/install/doc/reference_manual/html/index.html">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>API</h2>
+ </a>
+ <p>Doxygen documentation.</p>
+ </li>
+ <li class="grid-item">
+ <a href="https://developer.arm.com/architectures/security-architectures/platform-security-architecture">
+ <img alt="" src="_static/images/tfm.png"/>
+ <h2>PSA</h2>
+ </a>
+ <p>Platform Security Architecture (PSA) information.</p>
+ </li>
+ </ul>
+
.. toctree::
- :maxdepth: 2
+ :caption: Table of Contents
+ :name: mastertoc
+ :titlesonly:
+ :maxdepth: 1
:hidden:
- Home<docs/readme>
- docs/about/index
- docs/changelog
+ Home<self>
+ docs/introduction/index
+ docs/getting_started/index
+ docs/contributing/index
+ docs/reference/index
docs/design_documents/index
- docs/user_guides/index
- docs/processes/index
- docs/glossary
- docs/lic
+ platform/ext/index
+
.. toctree::
- :caption: Target platforms
:maxdepth: 2
- :glob:
:hidden:
+ :caption: Quick Links
- platform/**
-
-.. toctree::
- :caption: Tools
- :maxdepth: 2
- :glob:
- :hidden:
-
- tools/iat-verifier/*
-
-.. include:: docs/readme.rst
+ docs/reference/changelog
+ docs/reference/glossary
+ docs/contributing/lic
--------------
diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst
new file mode 100644
index 0000000..0fa3aae
--- /dev/null
+++ b/docs/introduction/index.rst
@@ -0,0 +1,14 @@
+Introduction
+============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Introduction
+ :glob:
+ :numbered:
+
+ readme
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/readme.rst b/docs/introduction/readme.rst
similarity index 89%
rename from docs/readme.rst
rename to docs/introduction/readme.rst
index 35e628a..610bddf 100644
--- a/docs/readme.rst
+++ b/docs/introduction/readme.rst
@@ -9,15 +9,15 @@
reference implementation of the Platform Security Architecture (PSA).
Terms ``TFM`` and ``TF-M`` are commonly used in documents and code and both
-refer to ``Trusted Firmware M.`` :doc:`Glossary </docs/glossary>` has the list
+refer to ``Trusted Firmware M.`` :doc:`Glossary </docs/reference/glossary>` has the list
of terms and abbreviations.
#######
License
#######
-The software is provided under a BSD-3-Clause :doc:`License </docs/lic>`.
+The software is provided under a BSD-3-Clause :doc:`License </docs/contributing/lic>`.
Contributions to this project are accepted under the same license with developer
-sign-off as described in the :doc:`Contributing Guidelines </docs/processes/contributing>`.
+sign-off as described in the :doc:`Contributing Guidelines </docs/contributing/contributing>`.
This project contains code from other projects as listed below. The code from
external projects is limited to ``app``, ``bl2``, ``lib`` and ``platform``
@@ -39,7 +39,7 @@
#############
Release Notes
#############
-The :doc:`Change Log & Release Notes </docs/changelog>` provides details of
+The :doc:`Change Log & Release Notes </docs/reference/changelog>` provides details of
major features of the release and platforms supported.
###############
@@ -67,20 +67,20 @@
To build & run TF-M:
- - Follow the :doc:`SW requirements guide </docs/user_guides/tfm_sw_requirement>`
+ - Follow the :doc:`SW requirements guide </docs/getting_started/tfm_sw_requirement>`
to set up your environment.
- Follow the
- :doc:`Build instructions </docs/user_guides/tfm_build_instruction>` to compile
+ :doc:`Build instructions </docs/getting_started/tfm_build_instruction>` to compile
and build the TF-M source.
- - Follow the :doc:`User guide </docs/user_guides/tfm_user_guide>` for information
+ - Follow the :doc:`User guide </docs/getting_started/tfm_user_guide>` for information
on running the example.
To port TF-M to a another system or OS, follow the
-:doc:`OS Integration Guide </docs/user_guides/tfm_integration_guide>`
+:doc:`OS Integration Guide </docs/getting_started/tfm_integration_guide>`
-Please also see the :doc:`glossary </docs/glossary>` of terms used in the project.
+Please also see the :doc:`glossary </docs/reference/glossary>` of terms used in the project.
-:doc:`Contributing Guidelines </docs/processes/contributing>` contains guidance on how to
+:doc:`Contributing Guidelines </docs/contributing/contributing>` contains guidance on how to
contribute to this project.
Further documents can be found in the ``docs`` folder.
diff --git a/docs/processes/index.rst b/docs/processes/index.rst
deleted file mode 100644
index d3e453e..0000000
--- a/docs/processes/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-Processes
-=========
-.. toctree::
- :maxdepth: 1
- :caption: Contents
- :glob:
- :numbered:
-
- *
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst
new file mode 100644
index 0000000..2502261
--- /dev/null
+++ b/docs/reference/changelog.rst
@@ -0,0 +1,12 @@
+##########################
+Change Log & Release Notes
+##########################
+
+This document contains a summary of the new features, changes, fixes and known
+issues in each release of Trusted Firmware-M.
+
+.. include:: ../reference/releases/1.0.rst
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/glossary.rst b/docs/reference/glossary.rst
similarity index 100%
rename from docs/glossary.rst
rename to docs/reference/glossary.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
new file mode 100644
index 0000000..02c1077
--- /dev/null
+++ b/docs/reference/index.rst
@@ -0,0 +1,16 @@
+Reference
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+ :numbered:
+
+ changelog
+ glossary
+ */index
+ /tools/index
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/changelog.rst b/docs/reference/releases/1.0.rst
similarity index 95%
rename from docs/changelog.rst
rename to docs/reference/releases/1.0.rst
index 47e1ea7..48903f5 100644
--- a/docs/changelog.rst
+++ b/docs/reference/releases/1.0.rst
@@ -1,10 +1,3 @@
-##########################
-Change Log & Release Notes
-##########################
-
-This document contains a summary of the new features, changes, fixes and known
-issues in each release of Trusted Firmware-M.
-
***********
Version 1.0
***********
@@ -74,9 +67,9 @@
Other supported platforms:
- - Dual CPU system:
+ - Dual Core Cortex-M system:
- - `Cypress PSoC64.
+ - `Cypress PSoc64.
<https://www.cypress.com/documentation/product-brochures/cypress-psoc-64-secure-microcontrollers>`__
Platform Limitations
diff --git a/docs/reference/releases/index.rst b/docs/reference/releases/index.rst
new file mode 100644
index 0000000..dc8aecb
--- /dev/null
+++ b/docs/reference/releases/index.rst
@@ -0,0 +1,12 @@
+Releases
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/core_test_services_integration_guide.rst b/docs/reference/services/core_test_services_integration_guide.rst
similarity index 100%
rename from docs/user_guides/services/core_test_services_integration_guide.rst
rename to docs/reference/services/core_test_services_integration_guide.rst
diff --git a/docs/reference/services/index.rst b/docs/reference/services/index.rst
new file mode 100644
index 0000000..30a2a8a
--- /dev/null
+++ b/docs/reference/services/index.rst
@@ -0,0 +1,12 @@
+Services
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.rst b/docs/reference/services/tfm_attestation_integration_guide.rst
similarity index 99%
rename from docs/user_guides/services/tfm_attestation_integration_guide.rst
rename to docs/reference/services/tfm_attestation_integration_guide.rst
index e0399b4..83e6703 100644
--- a/docs/user_guides/services/tfm_attestation_integration_guide.rst
+++ b/docs/reference/services/tfm_attestation_integration_guide.rst
@@ -489,9 +489,9 @@
- Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations
for MPS2 AN521 platform. More info in
- :doc:`tfm_build_instruction </docs/user_guides/tfm_build_instruction>`.
+ :doc:`tfm_build_instruction </docs/getting_started/tfm_build_instruction>`.
- Lunch FVP model in DS-5. More info in
- :doc:`tfm_user_guide </docs/user_guides/tfm_user_guide>`.
+ :doc:`tfm_user_guide </docs/getting_started/tfm_user_guide>`.
- Set a breakpoint in ``test/suites/attestation/attest_token_test.c``
in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned,
i.e. on line 859. Execute the code in the model until the breakpoint hits
diff --git a/docs/user_guides/services/tfm_audit_integration_guide.rst b/docs/reference/services/tfm_audit_integration_guide.rst
similarity index 100%
rename from docs/user_guides/services/tfm_audit_integration_guide.rst
rename to docs/reference/services/tfm_audit_integration_guide.rst
diff --git a/docs/user_guides/services/tfm_crypto_integration_guide.rst b/docs/reference/services/tfm_crypto_integration_guide.rst
similarity index 100%
rename from docs/user_guides/services/tfm_crypto_integration_guide.rst
rename to docs/reference/services/tfm_crypto_integration_guide.rst
diff --git a/docs/user_guides/services/tfm_its_integration_guide.rst b/docs/reference/services/tfm_its_integration_guide.rst
similarity index 100%
rename from docs/user_guides/services/tfm_its_integration_guide.rst
rename to docs/reference/services/tfm_its_integration_guide.rst
diff --git a/docs/user_guides/services/tfm_platform_integration_guide.rst b/docs/reference/services/tfm_platform_integration_guide.rst
similarity index 100%
rename from docs/user_guides/services/tfm_platform_integration_guide.rst
rename to docs/reference/services/tfm_platform_integration_guide.rst
diff --git a/docs/user_guides/services/tfm_ps_integration_guide.rst b/docs/reference/services/tfm_ps_integration_guide.rst
similarity index 98%
rename from docs/user_guides/services/tfm_ps_integration_guide.rst
rename to docs/reference/services/tfm_ps_integration_guide.rst
index 1f47204..4da23a5 100644
--- a/docs/user_guides/services/tfm_ps_integration_guide.rst
+++ b/docs/reference/services/tfm_ps_integration_guide.rst
@@ -158,7 +158,7 @@
``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More
information about the filesystem and flash interfaces can be found in the
:doc:`ITS integration guide
-</docs/user_guides/services/tfm_its_integration_guide>`.
+</docs/reference/services/tfm_its_integration_guide>`.
The structure containing info about the external flash device, used by the ITS
service to handle requests from the PS partition, is defined in
@@ -276,14 +276,14 @@
processing environment. It provides a dedicated API to retrieve the client ID
which performs the service request.
-:doc:`NS client identification documentation </docs/user_guides/tfm_ns_client_identification>`
+:doc:`NS client identification documentation </docs/getting_started/tfm_ns_client_identification>`
provides further details on how client identification works.
PS service uses that TF-M core API to retrieve the client ID and associate it
as the owner of an asset. Only the owner can read, write or delete that asset
based on the creation flags.
-The :doc:`integration guide </docs/user_guides/tfm_integration_guide>` provides further
+The :doc:`integration guide </docs/getting_started/tfm_integration_guide>` provides further
details of non-secure implementation requirements for TF-M.
Cryptographic Interface
diff --git a/docs/user_guides/services/tfm_secure_partition_addition.rst b/docs/reference/services/tfm_secure_partition_addition.rst
similarity index 100%
rename from docs/user_guides/services/tfm_secure_partition_addition.rst
rename to docs/reference/services/tfm_secure_partition_addition.rst
diff --git a/docs/user_guides/index.rst b/docs/user_guides/index.rst
deleted file mode 100644
index 79bdc5d..0000000
--- a/docs/user_guides/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-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
deleted file mode 100644
index 94aec92..0000000
--- a/docs/user_guides/services/index.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Services
-========
-.. toctree::
- :maxdepth: 1
- :caption: Contents
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
