Docs: Platform documentation rules
- Minimal rules for a platform documentation
- Adjust existing platforms according to the rules
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: Idcb85f8ed5d55aa6406cd48cdfcb558d92ff0647
diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst
index 8c7b3b6..b466a58 100644
--- a/docs/contributing/doc_guidelines.rst
+++ b/docs/contributing/doc_guidelines.rst
@@ -54,30 +54,19 @@
#. New introduced terms and abbreviations should be added to Glossary and
directly linked by the `:term:` notation across all documents using it.
-
**********************
Platform Documentation
**********************
The Documentation Build system provides an interface with the platform directory
-allowing maintainers to bundle platform specific documentation. **This behaviour
-needs to be explicitly enabled for each platform's space** by
-modifying the `platform/index.rst` (responsible for generating the
+allowing maintainers to bundle platform specific documentation. Platforms are
+grouped by vendor. **This behaviour needs to be explicitly enabled for each
+vendor's space** by providing the `<vendor>/index.rst` (responsible for generating the
:doc:`Platform Index File </platform/index>`) and adding a table of
-contents entry for the corresponding platform space.
-
+contents entry for the corresponding vendor's space.
The format and structure of this entry is not strictly defined, and allows
-flexible control of the platform's documentation space. In most cases it can be
-set to recursively match all documents under that directory.
-
-.. code-block:: restructuredtext
-
- .. toctree::
- :maxdepth: 4
- :caption: PLATFORM_X_CAPTION
- :glob:
-
- PLATFORM_X/**
+flexible control of vendor's and platform's documentation space.
+Follow the :ref:`platform_documentation` document for more details.
****************
Common Use Cases
@@ -89,7 +78,6 @@
Headers
=======
-
.. code-block:: restructuredtext
###################
@@ -112,7 +100,6 @@
Code Blocks
===========
-
The recommendation for code content, is to use the explicit code-block directive,
ideally with a defined lexer for the language the block contains.
@@ -228,7 +215,6 @@
*Copyright (c) XYZ *
-
Document Links
==============
@@ -255,7 +241,6 @@
document and create clickable quick access references to it for improved user
experience.
-
Glossary term
=============
@@ -263,7 +248,6 @@
entry to the :doc:`/glossary` and refer to it, using the `term:`
directive
-
.. code-block:: restructuredtext
HAL
@@ -297,4 +281,4 @@
--------------
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
index 4d2f3fe..6f4571d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -85,7 +85,7 @@
:maxdepth: 1
:hidden:
- Platform Selection<platform/index>
+ Platforms <platform/index>
building/tfm_build_instruction
configuration/index
integration_guide/index
diff --git a/docs/integration_guide/platform/documenting_platform.rst b/docs/integration_guide/platform/documenting_platform.rst
new file mode 100644
index 0000000..563307f
--- /dev/null
+++ b/docs/integration_guide/platform/documenting_platform.rst
@@ -0,0 +1,90 @@
+.. _platform_documentation:
+
+######################
+Platform Documentation
+######################
+
+This document describes conventions for platform documentation for easy and smooth
+integration into TF-M online documentation.
+
+**********
+Principles
+**********
+
+- Minimise TF-M requirements and maximise flexibility to let platform vendors
+ reuse existing documentation.
+
+- Platforms are grouped under vendors' name. There is space to keep general
+ information not specific to any of the vendors' platforms.
+
+- A Table Of Contents (TOC) structures platforms' documentation. There is no
+ defined template for platform documents.
+
+*****
+Rules
+*****
+
+- Platforms documentation is gathered in `/docs/platform` folder.
+ This folder is similar to the platforms implementation folder
+ `/platform/ext/target` but does not need to mirror its structure.
+
+- A vendor is represented by a subfolder with `index.rst` as an entry
+ point. This file may contain general materials about a vendor
+ not specific to a particular platform.
+
+- A vendor's `index.rst` shall carry a TOCtree structure with a list of all
+ supported platforms at the top level.
+
+- An explicit platform name is preferred in a vendor's TOCtree instead of use of
+ platform's title by default.
+
+.. note:
+ Do not forget to update the summary file after adding a new platform
+ `/docs/platform/platform_introduction.rst` included into TF-M introduction.
+
+*******
+Example
+*******
+
+Assuming a vendor `ABCD123` wants to add and document a new platform
+`Secure 1024` in TF-M. Here are the basic steps:
+
+1. Create a folder `/docs/platform/ABCD123/`
+
+2. Create a platform documentation under `/docs/platform/ABCD123`.
+ A natural choice is to put a new platform under `/docs/platform/ABCD123/Secure_1024`
+ folder but it's not required.
+
+3. Create a file `/docs/platform/ABCD123/index.rst` with a platform entry, presuming
+ it's location in `/docs/platform/ABCD123/Secure_1024/index.rst`:
+
+.. code-block:: rst
+
+ #################
+ ABCD123 platforms
+ #################
+
+ .. toctree::
+ Secure 1024 <Secure_1024/index>
+
+4. Finally, update `/docs/platform/index.rst` with a new vendor name:
+
+.. code-block:: rst
+
+ ##############
+ TF-M Platforms
+ ##############
+
+ .. toctree::
+ :maxdepth: 2
+ :glob:
+
+ Arm <arm/index.rst>
+ NXP <nxp/index.rst>
+ Cypress <cypress/index.rst>
+ ...
+ ABCD123 <ABCD123/index.rst>
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/integration_guide/platform/index.rst b/docs/integration_guide/platform/index.rst
index c76e327..a02134e 100644
--- a/docs/integration_guide/platform/index.rst
+++ b/docs/integration_guide/platform/index.rst
@@ -8,6 +8,7 @@
platform_folder.rst
platform_ext_folder.rst
porting_TFM_to_a_new_hardware
+ documenting_platform.rst
platform_provisioning.rst
platform_deprecation.rst
diff --git a/docs/platform/arm/index.rst b/docs/platform/arm/index.rst
index 68eb5c5..4bb36c4 100755
--- a/docs/platform/arm/index.rst
+++ b/docs/platform/arm/index.rst
@@ -3,7 +3,7 @@
#############
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
:titlesonly:
Corstone-1000 <corstone1000/readme.rst>
diff --git a/docs/platform/cypress/index.rst b/docs/platform/cypress/index.rst
new file mode 100644
index 0000000..b3305a6
--- /dev/null
+++ b/docs/platform/cypress/index.rst
@@ -0,0 +1,9 @@
+################
+Cypress platform
+################
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+
+ PSoC64 <psoc64/index.rst>
diff --git a/docs/platform/index.rst b/docs/platform/index.rst
index 4c53ebb..871395b 100644
--- a/docs/platform/index.rst
+++ b/docs/platform/index.rst
@@ -4,52 +4,15 @@
.. toctree::
:maxdepth: 2
- :caption: arm
- arm/index
-
-.. toctree::
- :maxdepth: 1
- :caption: NXP
- :glob:
-
- nxp/**
-
-.. toctree::
- :maxdepth: 1
- :caption: Cypress
- :glob:
-
- cypress/psoc64/index
-
-.. toctree::
- :maxdepth: 2
- :caption: STM
- :glob:
-
- stm/index
-
-.. toctree::
- :maxdepth: 1
- :caption: Nordic
- :glob:
-
- nordic_nrf/**
-
-.. toctree::
- :maxdepth: 1
- :caption: Laird Connectivity
- :glob:
-
- lairdconnectivity/**
-
-.. toctree::
- :maxdepth: 1
- :caption: Nuvoton
- :glob:
-
- nuvoton/**
+ Arm <arm/index>
+ Cypress <cypress/index>
+ Laird Connectivity <lairdconnectivity/index>
+ Nordic <nordic_nrf/index>
+ Nuvoton <nuvoton/index>
+ NXP <nxp/index>
+ STMICROELECTRONICS <stm/index>
--------------
-*Copyright (c) 2020-2021, Arm Limited. All rights reserved.*
+*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
diff --git a/docs/platform/lairdconnectivity/index.rst b/docs/platform/lairdconnectivity/index.rst
new file mode 100644
index 0000000..cb52760
--- /dev/null
+++ b/docs/platform/lairdconnectivity/index.rst
@@ -0,0 +1,9 @@
+###########################
+Laird Connectivity platform
+###########################
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+
+ BL5340 <bl5340_dvk_cpuapp/README.rst>
diff --git a/docs/platform/nordic_nrf/index.rst b/docs/platform/nordic_nrf/index.rst
new file mode 100644
index 0000000..17c4f29
--- /dev/null
+++ b/docs/platform/nordic_nrf/index.rst
@@ -0,0 +1,10 @@
+################
+Nordic platforms
+################
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+
+ nRF5340 <nrf5340dk_nrf5340_cpuapp/README.rst>
+ nRF9160 <nrf9160dk_nrf9160/README.rst>
diff --git a/docs/platform/nuvoton/index.rst b/docs/platform/nuvoton/index.rst
new file mode 100644
index 0000000..b59e748
--- /dev/null
+++ b/docs/platform/nuvoton/index.rst
@@ -0,0 +1,10 @@
+#################
+Nuvoton platforms
+#################
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+
+ NuMaker-PFM-M2351 <m2351/README.rst>
+ NuMaker-PFM-M2354 <m2354/README.rst>
diff --git a/docs/platform/nxp/index.rst b/docs/platform/nxp/index.rst
new file mode 100644
index 0000000..0ed452c
--- /dev/null
+++ b/docs/platform/nxp/index.rst
@@ -0,0 +1,9 @@
+############
+NXP platform
+############
+
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+
+ LPCXpresso55S69 <lpcxpresso55s69/README.rst>