doc: Convert internal links to RST format ...

Currently links between documents are using the format:

<path/to/><filename>.rst

This was required for services like GitHub because they render each
document in isolation - linking to another document is like linking
to any other file, just provide the full path.

However, with the new approach, the .rst files are only the raw
source for the documents. Once the documents have been rendered
the output is now in another format (HTML in our case) and so,
when linking to another document, the link must point to the
rendered version and not the .rst file.

The RST spec provides a few methods for linking between content.
The parent of this patch enabled the automatic creation of anchors
for document titles - we will use these anchors as the targets for
our links. Additional anchors can be added by hand if needed, on
section and sub-section titles, for example.

An example of this new format, for a document with the title
"Firmware Design" is :ref:`Firmware Design`.

One big advantage of this is that anchors are not dependent on
paths. We can then move documents around, even between directories,
without breaking any links between documents. Links will need to be
updated only if the title of a document changes.

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

Remove references to old project name from common files ...

The project has been renamed from "Arm Trusted Firmware (ATF)" to
"Trusted Firmware-A (TF-A)" long ago. A few references to the old
project name that still remained in various places have now been
removed.

This change doesn't affect any platform files. Any "ATF" references
inside platform files, still remain.

Change-Id: Id97895faa5b1845e851d4d50f5750de7a55bf99e
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

docs: removing references to GitHub ...

Change-Id: Ibdee91ad337ee362872924d93e82f5b5e47e63d9
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Further fixes to documentation links ...

Change-Id: Ib021c721652d96f6c06ea18741f19a72bba1d00f
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Fix documentation links ...

Change-Id: Ic09e74f22b43fba51ee17cd02b5e1dc5d8e0bb63
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

doc: Use proper note and warning annotations ...

The documentation contains plenty of notes and warnings. Enable
special rendering of these blocks by converting the note prefix
into a .. note:: annotation.

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

doc: Add minimal glossary ...

One of the current issues with the documentation is that terms and
abbreviations are frequently redefined. For example, we might have
a sentence like "... the SCP (System Control Processor) will ...".

These definitions might be repeated several times across pages, or
even within the same document. Equally, some of these abbreviations
are missed and are never expanded.

Sphinx provides a :term: keyword that takes some text and,
if that text is defined in a glossary document, links to its glossary
entry. Using this functionality will prevent repeated definitions
and will make the docs more maintainable by using a single
definition source.

The glossary added in this patch was created from a quick scrub of
the source code - there may be missing entries. The SDEI abbreviation
was used as an example.

Note that a global_substitutions file was created. This file contains
the RST 'replace' statements that convert plain text terms into linked
terms (by adding the ':term:' keyword to them). An example is:

.. |TF-A| replace:: :term:`TF-A`

The 'rst_prolog' variable in conf.py is used to inject this list of
replacements into each page. Terms must be surrounded with the pipe
character to be turned into links - this means that we can still
prevent certain terms from being linked if we don't want them to be.

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

doc: Remove per-page contents lists ...

These are no longer needed as there will always be a table of contents
rendered to the left of every page.

Some of these lists can be quite long and, when opening a page, the
reader sees nothing but a huge list of contents! After this patch,
the document contents are front-and-centre and the contents are
nicely rendered in the sidebar without duplication.

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

doc: Reword document titles ...

This patch attempts to standardise the document titles as well as
adding titles to documents that were missing one. The aim is to
remove needless references to "TF-A" or "Trusted Firmware" in the
title of every document and to make sure that the title matches
with the document content.

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

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>

doc: Fix heading levels for changelog ...

The change-log.rst file does not use the same symbols
as the other documents when organising its headings,
sub-headings and so on. In order to compile these
documents together with Sphinx, forming a top-level
index and a consistent structure, it is necessary to
normalise these.

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

doc: Clarify draft status of SPCI and SPRT specs ...

These SPM-related specifications are mentioned in the readme and
the change log. Update references to these specs to make it clear
that they are in draft form and are expected to change.

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

docs: List MB version dependency for Juno FWU as known issue ...

Change-Id: Ib37215ca4c9b515e54054290952eed5034582ba4
Signed-off-by: Soby Mathew <soby.mathew@arm.com>

doc: Update change log for v2.1 ...

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

Merge pull request #1818 from pbeesley-arm/doc-links ...

doc: Fix broken external links

doc: Fix broken external links ...

Using Sphinx linkcheck on the TF-A docs revealed some broken
or permanently-redirected links. These have been updated where
possible.

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

Doc: Remove useless escape characters ...

Just like has been done in the porting guide a couple of patches
earlier, kill all escaped underscore characters in all documents.

Change-Id: I7fb5b806412849761d9221a6ce3cbd95ec43d611
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

Correct typographical errors ...

Corrects typos in core code, documentation files, drivers, Arm
platforms and services.

None of the corrections affect code; changes are limited to comments
and other documentation.

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

Fix typos in changelog ...

Change-Id: Icc6fb03abb9b4ef85931b9e3d767b5a9c271b5f3
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Release docs updates for v2.0 release ...

Change-Id: Iaa5c586b65f0abdd4ddbdee4c73d07811a0aff49
Signed-off-by: Joanna Farley <joanna.farley@arm.com>

Readme and Change-log updates for v1.6 release ...

Change-Id: I7855c9d3de104975bf3249bdf291c428f001d07a
Signed-off-by: Joanna Farley <joanna.farley@arm.com>

Update change-log.rst for v1.5 ...

Updated change-log.rst with summary of changes since
release v1.4.

Change-Id: I56b5a30d13a5a7099942535cbaeff0e2a5c5804e
Signed-off-by: David Cunado <david.cunado@arm.com>

Update Arm TF references to TF-A ...

Update Arm Trusted Firmware references in the upstream documents to
Trusted Firmware-A (TF-A). This is for consistency with and
disambiguation from Trusted Firmware-M (TF-M).

Also update other Arm trademarks, e.g. ARM->Arm, ARMv8->Armv8-A.

Change-Id: I8bb0e18af29c6744eeea2dc6c08f2c10b20ede22
Signed-off-by: Dan Handley <dan.handley@arm.com>
Signed-off-by: David Cunado <david.cunado@arm.com>

Fix to change.log ...

With the migration to .rst from .md, the Issues Resolved and
Known Issues sections for v1.4 were using Header 1 format.

This patch changes to using Header 2 for these sections.

Change-Id: Ic3127d84eb169a65039fd4cc8284c6429302732d
Signed-off-by: David Cunado <david.cunado@arm.com>

Release v1.4: update change-log.rst ...

Updated change-log.rst with summary of changes since release v1.3.

Change-Id: Iecd31ed315bd9ad7ffe8bce6550f7c90e1e3a9b0
Signed-off-by: David Cunado <david.cunado@arm.com>

Manual fixes to reST documentations ...

Non-automated fixes to the converted documentation.

Change-Id: I61f3d37c7a8d6a56a7351048060b970c5b3751e4
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>

Convert documentation to reStructuredText ...

Due to recent issues in the rendering of the documentation on GitHub and
some long-standing issues like the lack of automatic table of content in
Markdown, the documentation has been converted to reStructuredText.
Basic constructs looks pretty similar to Markdown.

Automatically convert GitHub markdown documentation to reStructuredText
using pandoc.

Change-Id: If20b695acedc6d1b49c8d9fb64efd6b6ba23f4a9
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>