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/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