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.*