doc: Move documents into subdirectories

This change creates the following directories under docs/
in order to provide a grouping for the content:

- components
- design
- getting_started
- perf
- process

In each of these directories an index.rst file is created
and this serves as an index / landing page for each of the
groups when the pages are compiled. Proper layout of the
top-level table of contents relies on this directory/index
structure.

Without this patch it is possible to build the documents
correctly with Sphinx but the output looks messy because
there is no overall hierarchy.

Change-Id: I3c9f4443ec98571a56a6edf775f2c8d74d7f429f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

docs/design/index.rst

+System Design
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   auth-framework
+   cpu-specific-build-macros
+   firmware-design
+   interrupt-framework-design
+   psci-pd-tree
+   reset-design
+   trusted-board-boot

docs/interrupt-framework-design.rst → docs/design/interrupt-framework-design.rst

@@ -2,8 +2,7 @@ Trusted Firmware-A interrupt management design guide
 ====================================================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -1018,7 +1017,7 @@ TSP by returning ``SMC_UNK`` error.
 
 *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Porting Guide: ./porting-guide.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 
 .. |Image 1| image:: diagrams/sec-int-handling.png?raw=true

docs/psci-pd-tree.rst → docs/design/psci-pd-tree.rst

@@ -2,8 +2,7 @@ PSCI Power Domain Tree design
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 

docs/reset-design.rst → docs/design/reset-design.rst

@@ -2,8 +2,7 @@ Trusted Firmware-A reset design
 ===============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -158,9 +157,9 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31.
 *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
 
 .. _Firmware Design: firmware-design.rst
-.. _User Guide: user-guide.rst
+.. _User Guide: ../getting_started/user-guide.rst
 
-.. |Default reset code flow| image:: diagrams/default_reset_code.png?raw=true
-.. |Reset code flow with programmable reset address| image:: diagrams/reset_code_no_boot_type_check.png?raw=true
-.. |Reset code flow with single CPU released out of reset| image:: diagrams/reset_code_no_cpu_check.png?raw=true
-.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: diagrams/reset_code_no_checks.png?raw=true
+.. |Default reset code flow| image:: ../diagrams/default_reset_code.png?raw=true
+.. |Reset code flow with programmable reset address| image:: ../diagrams/reset_code_no_boot_type_check.png?raw=true
+.. |Reset code flow with single CPU released out of reset| image:: ../diagrams/reset_code_no_cpu_check.png?raw=true
+.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../diagrams/reset_code_no_checks.png?raw=true

docs/trusted-board-boot.rst → docs/design/trusted-board-boot.rst

@@ -2,8 +2,7 @@ Trusted Board Boot Design Guide
 ===============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 
@@ -234,7 +233,7 @@ for building and using the tool can be found in the `User Guide`_.
 
 .. _Firmware Update: firmware-update.rst
 .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
-.. _User Guide: user-guide.rst
+.. _User Guide: ../getting_started/user-guide.rst
 .. _Auth Framework: auth-framework.rst
 .. _TBBR-client: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
 .. _Trusted Board Boot Requirements (TBBR): `TBBR-client`_

docs/getting_started/index.rst

+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   user-guide
+   image-terminology
+   porting-guide
+   psci-lib-integration-guide
+   rt-svc-writers-guide

docs/porting-guide.rst → docs/getting_started/porting-guide.rst

@@ -2,13 +2,9 @@ Trusted Firmware-A Porting Guide
 ================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
---------------
-
 Introduction
 ------------
 
@@ -2366,7 +2362,7 @@ FVP can be configured to use either GICv2 or GICv3 depending on the build flag
 
 See also: `Interrupt Controller Abstraction APIs`__.
 
-.. __: platform-interrupt-controller-API.rst
+.. __: ../design/platform-interrupt-controller-API.rst
 
 Function : plat_interrupt_type_to_line() [mandatory]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2493,7 +2489,7 @@ value obtained from the interrupt controller when acknowledging an interrupt.
 The actual interrupt number shall be extracted from this raw value using the API
 `plat_ic_get_interrupt_id()`__.
 
-.. __: platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
+.. __: ../design/platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
 
 This function in Arm standard platforms using GICv2, reads the *Interrupt
 Acknowledge Register* (``GICC_IAR``). This changes the state of the highest

docs/psci-lib-integration-guide.rst → docs/getting_started/psci-lib-integration-guide.rst

@@ -2,8 +2,6 @@ PSCI Library Integration guide for Armv8-A AArch32 systems
 ==========================================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
@@ -550,5 +548,5 @@ workarounds.
 .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
 .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Porting Guide: porting-guide.rst
-.. _Firmware Design: ./firmware-design.rst
+.. _Porting Guide: ../getting_started/porting-guide.rst
+.. _Firmware Design: ../design/firmware-design.rst

docs/rt-svc-writers-guide.rst → docs/getting_started/rt-svc-writers-guide.rst

@@ -2,13 +2,9 @@ Trusted Firmware-A EL3 runtime service writer's guide
 =====================================================
 
 
-.. section-numbering::
-    :suffix: .
 
 .. contents::
 
---------------
-
 Introduction
 ------------
 
@@ -307,9 +303,9 @@ provide this information....
 
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Firmware Design: ./firmware-design.rst
-.. _services: ../services
-.. _lib/psci: ../lib/psci
-.. _runtime_svc.h: ../include/common/runtime_svc.h
-.. _smccc.h: ../include/lib/smccc.h
-.. _std_svc_setup.c: ../services/std_svc/std_svc_setup.c
+.. _Firmware Design: ../designb_documents/firmware-design.rst
+.. _services: ../../services
+.. _lib/psci: ../../lib/psci
+.. _runtime_svc.h: ../../include/common/runtime_svc.h
+.. _smccc.h: ../../include/lib/smccc.h
+.. _std_svc_setup.c: ../../services/std_svc/std_svc_setup.c

docs/user-guide.rst → docs/getting_started/user-guide.rst

@@ -2,8 +2,7 @@ Trusted Firmware-A User Guide
 =============================
 
 
-.. section-numbering::
-    :suffix: .
+
 
 .. contents::
 

docs/index.rst

-Arm Trusted Firmware-A Documentation Index
-==========================================
+Trusted Firmware-A Documentation
+================================
 
 .. toctree::
    :maxdepth: 1
-   :caption: Design Documents
+   :caption: Contents
 
-   arm-sip-service
-   auth-framework
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Release Notes
+   getting_started/index
+   process/index
+   components/index
+   design/index
+   plat/index
+   perf/index
+   security_advisories/index
+   readme
    change-log
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Guides
-
-   .. toctree::
-   :maxdepth: 1
-   :caption: Policies
-   cpu-specific-build-macros
-   exception-handling
-   firmware-design
-   firmware-update
-   interrupt-framework-design
-   platform-compatibility-policy
-   platform-interrupt-controller-API
-   porting-guide
-   psci-lib-integration-guide
-   psci-pd-tree
-   ras
-   reset-design
-   rt-svc-writers-guide
-   sdei
-   secure-partition-manager-design
-   trusted-board-boot
-   user-guide
-   xlat-tables-lib-v2-design
+   maintainers
+   acknowledgements
 
 Indices and tables
 ==================

docs/perf/index.rst

+Performance & Testing
+=====================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   psci-performance-juno

docs/plat/index.rst

+Platform Ports
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+   :numbered:
+
+   allwinner
+   fvp_ve
+   imx8
+   imx8m
+   intel-stratix10
+   ls1043a
+   meson-gxbb
+   meson-gxl
+   mt8183
+   nvidia-tegra
+   poplar
+   qemu
+   rcar-gen3
+   rockchip
+   rpi3
+   socionext-uniphier
+   stm32mp1
+   synquacer
+   ti-k3
+   warp7
+   xilinx-zynqmp