1.. _platform_documentation:
2
3######################
4Platform Documentation
5######################
6
7This document describes conventions for platform documentation for easy and smooth
8integration into TF-M online documentation.
9
10**********
11Principles
12**********
13
14- Minimise TF-M requirements and maximise flexibility to let platform vendors
15  reuse existing documentation.
16
17- Platforms are grouped under vendors' name. There is space to keep general
18  information not specific to any of the vendors' platforms.
19
20- A Table Of Contents (TOC) structures platforms' documentation. There is no
21  defined template for platform documents.
22
23*****
24Rules
25*****
26
27- Platforms documentation is gathered in `/docs/platform` folder.
28  This folder is similar to the platforms implementation folder
29  `/platform/ext/target` but does not need to mirror its structure.
30
31- A vendor is represented by a subfolder with `index.rst` as an entry
32  point. This file may contain general materials about a vendor
33  not specific to a particular platform.
34
35- A vendor's `index.rst` shall carry a TOCtree structure with a list of all
36  supported platforms at the top level.
37
38- An explicit platform name is preferred in a vendor's TOCtree instead of use of
39  platform's title by default.
40
41.. note::
42  Do not forget to update the summary file after adding a new platform
43  `/docs/platform/platform_introduction.rst` included into TF-M introduction.
44
45*******
46Example
47*******
48
49Assuming a vendor `ABCD123` wants to add and document a new platform
50`Secure 1024` in TF-M. Here are the basic steps:
51
521. Create a folder `/docs/platform/ABCD123/`
53
542. Create a platform documentation under `/docs/platform/ABCD123`.
55   A natural choice is to put a new platform under `/docs/platform/ABCD123/Secure_1024`
56   folder but it's not required.
57
583. Create a file `/docs/platform/ABCD123/index.rst` with a platform entry, presuming
59   it's location in `/docs/platform/ABCD123/Secure_1024/index.rst`:
60
61.. code-block:: rst
62
63  #################
64  ABCD123 platforms
65  #################
66
67  .. toctree::
68  Secure 1024 <Secure_1024/index>
69
704. Finally, update `/docs/platform/index.rst` with a new vendor name:
71
72.. code-block:: rst
73
74  ##############
75  TF-M Platforms
76  ##############
77
78  .. toctree::
79      :maxdepth: 2
80      :glob:
81
82      Arm <arm/index.rst>
83      NXP <nxp/index.rst>
84      Cypress <cypress/index.rst>
85      ...
86      ABCD123 <ABCD123/index.rst>
87
88--------------
89
90*Copyright (c) 2023, Arm Limited. All rights reserved.*
91