Merge changes from topic "pb/sphinx-doc" into integration

* changes:
  doc: Use proper note and warning annotations
  doc: Refactor contributor acknowledgements
  doc: Reorganise images and update links
  doc: Set correct syntax highlighting style
  doc: Add minimal glossary
  doc: Remove per-page contents lists
  doc: Make checkpatch ignore rst files
  doc: Format security advisory titles and headings
  doc: Reformat platform port documents
  doc: Normalise section numbering and headings
  doc: Reword document titles

Makefile

@@ -55,7 +55,7 @@ ROOT_DIRS_TO_CHECK	:=	$(sort $(filter-out			\
 					lib				\
 					include				\
 					docs				\
-					%.md,				\
+					%.rst,				\
 					$(wildcard *)))
 CHECK_PATHS		:=	${ROOT_DIRS_TO_CHECK}			\
 				${INC_DIRS_TO_CHECK}			\
@@ -815,7 +815,7 @@ realclean distclean:
 checkcodebase:		locate-checkpatch
 	@echo "  CHECKING STYLE"
 	@if test -d .git ; then						\
-		git ls-files | grep -E -v 'libfdt|libc|docs|\.md' |	\
+		git ls-files | grep -E -v 'libfdt|libc|docs|\.rst' |	\
 		while read GIT_FILE ;					\
 		do ${CHECKPATCH} ${CHECKCODE_ARGS} -f $$GIT_FILE ;	\
 		done ;							\
@@ -825,7 +825,7 @@ checkcodebase:		locate-checkpatch
 		 -not -iwholename "*libfdt*"				\
 		 -not -iwholename "*libc*"				\
 		 -not -iwholename "*docs*"				\
-		 -not -iwholename "*.md"				\
+		 -not -iwholename "*.rst"				\
 		 -exec ${CHECKPATCH} ${CHECKCODE_ARGS} -f {} \; ;	\
 	fi
 

docs/acknowledgements.rst

-**Note: This file is only relevant for legacy contributions, to acknowledge the
-specific contributors referred to in "Arm Limited and Contributors" copyright
-notices. As contributors are now encouraged to put their name or company name
-directly into the copyright notices, this file is not relevant for new
-contributions.**
-
 Contributor Acknowledgements
 ============================
 
-Companies
----------
-
-Linaro Limited
-
-NVIDIA Corporation
-
-Socionext Inc.
-
-Xilinx, Inc.
-
-NXP Semiconductors
-
-Marvell International Ltd.
-
-STMicroelectronics
-
-Individuals
------------
+.. note::
+   This file is only relevant for legacy contributions, to acknowledge the
+   specific contributors referred to in "Arm Limited and Contributors" copyright
+   notices. As contributors are now encouraged to put their name or company name
+   directly into the copyright notices, this file is not relevant for new
+   contributions.
+
+- Linaro Limited
+- Marvell International Ltd.
+- NVIDIA Corporation
+- NXP Semiconductors
+- Socionext Inc.
+- STMicroelectronics
+- Xilinx, Inc.

docs/change-log.rst

-Trusted Firmware-A Release Notes
-================================
+Change Log & Release Notes
+==========================
 
 This document contains a summary of the new features, changes, fixes and known
 issues in each release of Trusted Firmware-A.
 
-.. contents::
-
 Version 2.1
 -----------
 
@@ -296,12 +294,12 @@ Changed
 
 - SDEI
    - Added support for unconditionally resuming secure world execution after
-     SDEI event processing completes
+     |SDEI| event processing completes
 
-     SDEI interrupts, although targeting EL3, occur on behalf of the non-secure
+     |SDEI| interrupts, although targeting EL3, occur on behalf of the non-secure
      world, and may have higher priority than secure world
      interrupts. Therefore they might preempt secure execution and yield
-     execution to the non-secure SDEI handler. Upon completion of SDEI event
+     execution to the non-secure |SDEI| handler. Upon completion of |SDEI| event
      handling, resume secure execution if it was preempted.
 
 - Translation Tables (XLAT)
@@ -503,7 +501,7 @@ New Features
 
    -  Implement dynamic mitigation for CVE-2018-3639 on Cortex-A76
 
-   -  Ensure SDEI handler executes with CVE-2018-3639 mitigation enabled
+   -  Ensure |SDEI| handler executes with CVE-2018-3639 mitigation enabled
 
 -  Introduce RAS handling on AArch64
 
@@ -623,7 +621,7 @@ New Features
 
    -  Introduce jump primitives for BL31
 
-   -  Mask events after CPU wakeup in SDEI dispatcher to conform to the
+   -  Mask events after CPU wakeup in |SDEI| dispatcher to conform to the
       specification
 
 -  Misc TF-A Core Common Code Enhancements
@@ -787,8 +785,8 @@ New features
       management and security services. The SPM is the firmware component that
       is responsible for managing a Secure Partition.
 
-   -  SDEI dispatcher: Support for interrupt-based SDEI events and all
-      interfaces as defined by the SDEI specification v1.0, see
+   -  SDEI dispatcher: Support for interrupt-based |SDEI| events and all
+      interfaces as defined by the |SDEI| specification v1.0, see
       `SDEI Specification`_
 
    -  Exception Handling Framework (EHF): Framework that allows dispatching of
@@ -1188,7 +1186,8 @@ New features
 -  Migrated to use SPDX[0] license identifiers to make software license
    auditing simpler.
 
-   *NOTE:* Files that have been imported by FreeBSD have not been modified.
+   .. note::
+      Files that have been imported by FreeBSD have not been modified.
 
    [0]: https://spdx.org/
 
@@ -2207,7 +2206,8 @@ New features
    be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation
    FVP.
 
-   NOTE: The software will not work on Version 1.0 of the Foundation FVP.
+   .. note::
+      The software will not work on Version 1.0 of the Foundation FVP.
 
 -  Enabled third party contributions. Added a new contributing.md containing
    instructions for how to contribute and updated copyright text in all files
@@ -2238,15 +2238,18 @@ New features
    FIP from NOR flash, although some support for image loading using semi-
    hosting is retained.
 
-   NOTE: Building a FIP by default is a non-backwards-compatible change.
+   .. note::
+      Building a FIP by default is a non-backwards-compatible change.
 
-   NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
-   DRAM instead of expecting this to be pre-loaded at known location. This is
-   also a non-backwards-compatible change.
+   .. note::
+      Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
+      DRAM instead of expecting this to be pre-loaded at known location. This is
+      also a non-backwards-compatible change.
 
-   NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
-   it knows the new location to execute from and no longer needs to copy
-   particular code modules to DRAM itself.
+   .. note::
+      Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
+      it knows the new location to execute from and no longer needs to copy
+      particular code modules to DRAM itself.
 
 -  Reworked BL2 to BL3-1 handover interface. A new composite structure
    (bl31_args) holds the superset of information that needs to be passed from
@@ -2272,8 +2275,11 @@ New features
    Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD
    implements Secure Monitor functionality such as world switching and
    EL1 context management, and is responsible for communication with the TSP.
-   NOTE: The TSPD does not yet contain support for secure world interrupts.
-   NOTE: The TSP/TSPD is not built by default.
+
+   .. note::
+      The TSPD does not yet contain support for secure world interrupts.
+   .. note::
+      The TSP/TSPD is not built by default.
 
 Issues resolved since last release
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/components/arm-sip-service.rst

-Arm SiP Service
-===============
+Arm SiP Services
+================
 
 This document enumerates and describes the Arm SiP (Silicon Provider) services.
 

docs/components/exception-handling.rst

-Exception Handling Framework in Trusted Firmware-A
-==================================================
-
-
-
-
-.. contents::
-    :depth: 2
-
-.. |EHF| replace:: Exception Handling Framework
-.. |TF-A| replace:: Trusted Firmware-A
+Exception Handling Framework
+============================
 
 This document describes various aspects of handling exceptions by Runtime
 Firmware (BL31) that are targeted at EL3, other than SMCs. The |EHF| takes care
@@ -54,11 +45,11 @@ exceptions are targeted at and handled in EL3. For instance:
 
 -  The Arm `SDEI specification`_ defines interfaces through which Normal world
    interacts with the Runtime Firmware in order to request notification of
-   system events. The SDEI specification requires that these events are notified
-   even when the Normal world executes with the exceptions masked. This too
-   implies that firmware-first handling is required, where the events are first
-   received by the EL3 firmware, and then dispatched to Normal world through
-   purely software mechanism.
+   system events. The |SDEI| specification requires that these events are
+   notified even when the Normal world executes with the exceptions masked. This
+   too implies that firmware-first handling is required, where the events are
+   first received by the EL3 firmware, and then dispatched to Normal world
+   through purely software mechanism.
 
 For |TF-A|, firmware-first handling means that asynchronous exceptions are
 suitably routed to EL3, and the Runtime Firmware (BL31) is extended to include
@@ -79,8 +70,8 @@ choose to:
    processing of the error to dedicated software stack running at lower secure
    ELs (as above); additionally, the Normal world may also be required to
    participate in the handling, or be notified of such events (for example, as
-   an SDEI event). In this scheme, exception handling potentially and maximally
-   spans all ELs in both Secure and Normal worlds.
+   an |SDEI| event). In this scheme, exception handling potentially and
+   maximally spans all ELs in both Secure and Normal worlds.
 
 On any given system, all of the above handling models may be employed
 independently depending on platform choice and the nature of the exception
@@ -116,7 +107,7 @@ for more than one priority level.
 
 .. _ehf-figure:
 
-.. image:: ../draw.io/ehf.svg
+.. image:: ../resources/diagrams/draw.io/ehf.svg
 
 A priority level is *active* when a handler at that priority level is currently
 executing in EL3, or has delegated the execution to a lower EL. For interrupts,
@@ -202,7 +193,7 @@ priority assignment:
    6 and 5), the platform can partition into 4 secure priority ranges: ``0x0``,
    ``0x20``, ``0x40``, and ``0x60``. See `Interrupt handling example`_.
 
-Note:
+.. note::
 
    The Arm GIC architecture requires that a GIC implementation that supports two
    security states must implement at least 32 priority levels; i.e., at least 5
@@ -224,7 +215,7 @@ priority level descriptors. Each entry in the array is of type
 ``ehf_pri_desc_t``, and declares a priority level, and shall be populated by the
 ``EHF_PRI_DESC()`` macro.
 
-Note:
+.. warning::
 
    The macro ``EHF_PRI_DESC()`` installs the descriptors in the array at a
    computed index, and not necessarily where the macro is placed in the array.
@@ -609,8 +600,8 @@ should carefully consider the assignment of priorities to dispatchers integrated
 into runtime firmware. The platform should sensibly delineate priority to
 various dispatchers according to their nature. In particular, dispatchers of
 critical nature (RAS, for example) should be assigned higher priority than
-others (SDEI, for example); and within SDEI, Critical priority SDEI should be
-assigned higher priority than Normal ones.
+others (|SDEI|, for example); and within |SDEI|, Critical priority
+|SDEI| should be assigned higher priority than Normal ones.
 
 Limitations
 -----------

docs/components/firmware-update.rst

-Trusted Firmware-A - Firmware Update design guide
-=================================================
-
-
-
-
-.. contents::
-
---------------
+Firmware Update (FWU)
+=====================
 
 Introduction
 ------------
@@ -407,5 +400,5 @@ This is only allowed if the image is not being executed.
 .. _Authentication Framework Design: ./auth-framework.rst
 .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
 
-.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
-.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
+.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
+.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png

docs/components/platform-interrupt-controller-API.rst

-Platform Interrupt Controller API documentation
-===============================================
-
-
-
-.. contents::
+Platform Interrupt Controller API
+=================================
 
 This document lists the optional platform interrupt controller API that
 abstracts the runtime configuration and control of interrupt controller from the

docs/components/ras.rst

-RAS support in Trusted Firmware-A
-=================================
-
-
-
-.. contents::
-    :depth: 2
+Reliability, Availability, and Serviceability (RAS) Extensions
+==============================================================
 
 .. |EHF| replace:: Exception Handling Framework
 .. |TF-A| replace:: Trusted Firmware-A
@@ -44,7 +39,7 @@ be set ``1``.
 
 .. _ras-figure:
 
-.. image:: ../draw.io/ras.svg
+.. image:: ../resources/diagrams/draw.io/ras.svg
 
 See more on `Engaging the RAS framework`_.
 

docs/components/romlib-design.rst

 Library at ROM
 ==============
 
-.. section-numbering::
-    :suffix: .
-
-.. contents::
-
 This document provides an overview of the "library at ROM" implementation in
 Trusted Firmware-A (TF-A).
 
@@ -28,7 +23,7 @@ are placed in ROM. The capabilities of the "library at ROM" are:
 Index file
 ~~~~~~~~~~
 
-.. image:: diagrams/romlib_design.png
+.. image:: ../resources/diagrams/romlib_design.png
     :width: 600
 
 Library at ROM is described by an index file with the list of functions to be
@@ -59,7 +54,7 @@ For an index file example, refer to ``lib/romlib/jmptbl.i``.
 Wrapper functions
 ~~~~~~~~~~~~~~~~~
 
-.. image:: diagrams/romlib_wrapper.png
+.. image:: ../resources/diagrams/romlib_wrapper.png
     :width: 600
 
 When invoking a function of the "library at ROM", the calling sequence is as
@@ -111,7 +106,7 @@ The environment variable ``CROSS_COMPILE`` must be set as per the user guide.
 In the below example the usage of ROMLIB together with mbed TLS is demonstrated
 to showcase the benefits of library at ROM - it's not mandatory.
 
-::
+.. code:: shell
 
     make PLAT=fvp                                                   \
     MBEDTLS_DIR=</path/to/mbedtls/>                                 \

docs/components/sdei.rst

 SDEI: Software Delegated Exception Interface
 ============================================
 
-.. contents::
-    :depth: 2
-
 This document provides an overview of the SDEI dispatcher implementation in
 Trusted Firmware-A (TF-A).
 
@@ -29,7 +26,7 @@ The following figure depicts a general sequence involving SDEI client executing
 at EL2 and an event dispatch resulting from the triggering of a bound interrupt.
 A commentary is provided below:
 
-.. image:: ../plantuml/sdei_general.svg
+.. image:: ../resources/diagrams/plantuml/sdei_general.svg
 
 As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and
 the SDEI dispatcher returns a platform dynamic event number [2]. The client then
@@ -227,7 +224,7 @@ activity, such as receiving a Secure interrupt or an exception.
 The SDEI dispatcher implementation provides ``sdei_dispatch_event()`` API for
 this purpose. The API has the following signature:
 
-::
+.. code:: c
 
         int sdei_dispatch_event(int ev_num);
 
@@ -237,7 +234,7 @@ on success, or ``-1`` on failure.
 The following figure depicts a scenario involving explicit dispatch of SDEI
 event. A commentary is provided below:
 
-.. image:: ../plantuml/sdei_explicit_dispatch.svg
+.. image:: ../resources/diagrams/plantuml/sdei_explicit_dispatch.svg
 
 As part of initialisation, the SDEI client registers a handler for a platform
 event [1], enables the event [3], and unmasks the current PE [5]. Note that,

docs/components/secure-partition-manager-design.rst

-*******************************
-Secure Partition Manager Design
-*******************************
-
-
-
-.. contents::
+Secure Partition Manager
+************************
 
 Background
 ==========
@@ -135,7 +130,7 @@ First, build the Standalone MM Secure Partition. To build it, refer to the
 Then build TF-A with SPM support and include the Standalone MM Secure Partition
 image in the FIP:
 
-::
+.. code:: shell
 
     BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \
     make PLAT=fvp ENABLE_SPM=1 ARM_BL31_IN_DRAM=1 fip all
@@ -819,5 +814,5 @@ Error Codes
 .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
 .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 
-.. |Image 1| image:: ../diagrams/secure_sw_stack_tos.png
-.. |Image 2| image:: ../diagrams/secure_sw_stack_sp.png
+.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png
+.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png

docs/components/spd/index.rst

@@ -4,7 +4,6 @@ Secure Payload Dispatcher (SPD)
 .. toctree::
    :maxdepth: 1
    :caption: Contents
-   :numbered:
 
    optee-dispatcher
    tlk-dispatcher

docs/components/spd/tlk-dispatcher.rst

@@ -15,7 +15,7 @@ Once a BL32 is ready, TLKD can be included in the image by adding "SPD=tlkd"
 to the build command.
 
 Trusted Little Kernel (TLK)
-===========================
+---------------------------
 
 TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software
 (FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which
@@ -54,20 +54,20 @@ TLK and OTE can be found in the Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.p
 manual located under the "documentation" directory\_.
 
 Build TLK
-=========
+---------
 
 To build and execute TLK, follow the instructions from "Building a TLK Device"
 section from Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.pdf manual.
 
 Input parameters to TLK
-=======================
+-----------------------
 
 TLK expects the TZDRAM size and a structure containing the boot arguments. BL2
 passes this information to the EL3 software as members of the bl32\_ep\_info
 struct, where bl32\_ep\_info is part of bl31\_params\_t (passed by BL2 in X0)
 
-Example:
---------
+Example
+~~~~~~~
 
 ::
 

docs/components/spd/trusty-dispatcher.rst

@@ -9,7 +9,7 @@ Open Source Project (AOSP) webpage for Trusty hosted at
 https://source.android.com/security/trusty
 
 Boot parameters
-===============
+---------------
 
 Custom boot parameters can be passed to Trusty by providing a platform
 specific function:
@@ -26,7 +26,7 @@ can be set to a platform specific parameter block, and ``args->arg2``
 should then be set to the size of that block.
 
 Supported platforms
-===================
+-------------------
 
 Out of all the platforms supported by Trusted Firmware-A, Trusty is only
 verified and supported by NVIDIA's Tegra SoCs.

docs/components/xlat-tables-lib-v2-design.rst

-Translation Tables Library Design
+Translation (XLAT) Tables Library
 =================================
 
-
-
-
-.. contents::
-
-
 This document describes the design of the translation tables library (version 2)
 used by Trusted Firmware-A (TF-A). This library provides APIs to create page
 tables based on a description of the memory layout, as well as setting up system
@@ -424,4 +418,4 @@ mapping cannot be cached in the TLBs.
 .. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
 .. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
 .. _Porting Guide: ../getting_started/porting-guide.rst
-.. |Alignment Example| image:: ../diagrams/xlat_align.png?raw=true
+.. |Alignment Example| image:: ../resources/diagrams/xlat_align.png

docs/conf.py

@@ -9,6 +9,8 @@
 #
 # See the options documentation at http://www.sphinx-doc.org/en/master/config
 
+import os
+
 # -- Project information -----------------------------------------------------
 
 project = 'Trusted Firmware-A'
@@ -16,7 +18,6 @@ project = 'Trusted Firmware-A'
 version = '2.1'
 release = version # We don't need these to be distinct
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -48,6 +49,10 @@ exclude_patterns = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Load the contents of the global substitutions file into the 'rst_prolog'
+# variable. This ensures that the substitutions are all inserted into each page.
+with open('global_substitutions.txt', 'r') as subs:
+  rst_prolog = subs.read()
 
 # -- Options for HTML output -------------------------------------------------
 

docs/design/auth-framework.rst

-Abstracting a Chain of Trust
-============================
-
-
-
-
-.. contents::
+Authentication Framework & Chain of Trust
+=========================================
 
 The aim of this document is to describe the authentication framework
 implemented in Trusted Firmware-A (TF-A). This framework fulfills the
@@ -413,7 +408,7 @@ An IPL must provide functions with the following prototypes:
 
 An IPL for each type must be registered using the following macro:
 
-::
+.. code:: c
 
     REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param)
 
@@ -958,9 +953,11 @@ sources in the build for the various algorithms. Setting the variable to
 `rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS
 library.
 
-Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
-be defined in the platform Makefile. It will make mbed TLS use an implementation
-of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
+.. note::
+   If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
+   be defined in the platform Makefile. It will make mbed TLS use an
+   implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but
+   slower (~30%).
 
 --------------
 

docs/design/cpu-specific-build-macros.rst

 Arm CPU Specific Build Macros
 =============================
 
-
-
-
-.. contents::
-
 This document describes the various build options present in the CPU specific
 operations framework to enable errata workarounds and to enable optimizations
 for a specific CPU on a platform.

docs/design/firmware-design.rst

-Trusted Firmware-A design
-=========================
-
-
-
-
-.. contents::
+Firmware Design
+===============
 
 Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot
 Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference
@@ -1146,8 +1141,10 @@ returning through EL3 and running the non-trusted firmware (BL33):
    ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
    invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
    entrypoint.
-   NOTE: The Test SPD service included with TF-A provides one implementation
-   of such a mechanism.
+
+   .. note::
+      The Test SPD service included with TF-A provides one implementation
+      of such a mechanism.
 
    On completion BL32 returns control to BL31 via a SMC, and on receipt the
    SPD service handler invokes the synchronous call return mechanism to return
@@ -1680,8 +1677,9 @@ The location of the BL32 image will result in different memory maps. This is
 illustrated for both FVP and Juno in the following diagrams, using the TSP as
 an example.
 
-Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
-layout of the other images in Trusted SRAM.
+.. note::
+   Loading the BL32 image in TZC secured DRAM doesn't change the memory
+   layout of the other images in Trusted SRAM.
 
 CONFIG section in memory layouts shown below contains:
 
@@ -2220,8 +2218,9 @@ The default memory layout for each BL image is as follows:
        |       Code        |
        +-------------------+ BLx_BASE
 
-Note: The 2KB alignment for the exception vectors is an architectural
-requirement.
+.. note::
+   The 2KB alignment for the exception vectors is an architectural
+   requirement.
 
 The read-write data start on a new memory page so that they can be mapped with
 read-write permissions, whereas the code and read-only data below are configured
@@ -2309,7 +2308,7 @@ result in build error. Subscribing to an undefined event however won't.
 Subscribed handlers must be of type ``pubsub_cb_t``, with following function
 signature:
 
-::
+.. code:: c
 
    typedef void* (*pubsub_cb_t)(const void *arg);
 
@@ -2336,7 +2335,7 @@ A publisher that wants to publish event ``foo`` would:
 
 -  Define the event ``foo`` in the ``pubsub_events.h``.
 
-   ::
+   .. code:: c
 
       REGISTER_PUBSUB_EVENT(foo);
 
@@ -2472,7 +2471,7 @@ respectively.
 From outside TF-A, timestamps for individual CPUs can be retrieved by calling
 into ``pmf_smc_handler()``.
 
-.. code:: c
+::
 
     Interface : pmf_smc_handler()
     Argument  : unsigned int smc_fid, u_register_t x1,
@@ -2602,7 +2601,7 @@ Platform may choose to not define straight the toolchain target architecture
 directive by defining ``MARCH32_DIRECTIVE``.
 I.e:
 
-::
+.. code:: make
 
    MARCH32_DIRECTIVE := -mach=armv7-a
 
@@ -2684,4 +2683,4 @@ References
 .. _ROMLIB Design: romlib-design.rst
 .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
 
-.. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true
+.. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png

docs/design/interrupt-framework-design.rst

-Trusted Firmware-A interrupt management design guide
-====================================================
-
-
-
-
-.. contents::
+Interrupt Management Framework 
+==============================
 
 This framework is responsible for managing interrupts routed to EL3. It also
 allows EL3 software to configure the interrupt routing behavior. Its main
@@ -53,7 +48,7 @@ the exception level(s) it is handled in.
 The following constants define the various interrupt types in the framework
 implementation.
 
-::
+.. code:: c
 
     #define INTR_TYPE_S_EL1      0
     #define INTR_TYPE_EL3        1
@@ -421,8 +416,9 @@ runtime.
 Test secure payload dispatcher behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
-``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
+.. note::
+   Where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
+   ``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
 
 The TSPD only handles Secure-EL1 interrupts and is provided with the following
 routing model at build time.
@@ -1020,5 +1016,5 @@ TSP by returning ``SMC_UNK`` error.
 .. _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
-.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true
+.. |Image 1| image:: ../resources/diagrams/sec-int-handling.png
+.. |Image 2| image:: ../resources/diagrams/non-sec-int-handling.png