Skip to content

GitLab

Switch branch/tag
  1. 21 Jan, 2021 1 commit
  3. 17 Nov, 2020 1 commit
  5. 16 Apr, 2020 1 commit
  7. 01 Apr, 2020 1 commit
  9. 13 Nov, 2019 1 commit
  11. 21 Oct, 2019 1 commit
  13. 08 Oct, 2019 1 commit
    • Paul Beesley's avatar
      doc: Convert internal links to RST format · 34760951
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      34760951
  15. 10 Jul, 2019 1 commit
  17. 08 Jul, 2019 1 commit
  19. 30 May, 2019 1 commit
  21. 28 May, 2019 1 commit
  23. 22 May, 2019 4 commits
    • Paul Beesley's avatar
      doc: Use proper note and warning annotations · e1c5026a
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      e1c5026a
    • Paul Beesley's avatar
      doc: Add minimal glossary · 8f62ca7b
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      8f62ca7b
    • Paul Beesley's avatar
      doc: Remove per-page contents lists · 57354abb
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      57354abb
    • Paul Beesley's avatar
      doc: Reword document titles · 8aa05055
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      8aa05055
  25. 21 May, 2019 1 commit
    • Paul Beesley's avatar
      doc: Move documents into subdirectories · 40d553cf
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      40d553cf
  27. 05 Apr, 2019 1 commit
    • Paul Beesley's avatar
      doc: Fix heading levels for changelog · c48991e1
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      c48991e1
  29. 29 Mar, 2019 1 commit
  31. 28 Mar, 2019 1 commit
  33. 27 Mar, 2019 1 commit
  35. 08 Feb, 2019 2 commits
  37. 15 Jan, 2019 1 commit
    • Paul Beesley's avatar
      Correct typographical errors · 8aabea33
      Paul Beesley authored 
      

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: default avatarPaul Beesley <paul.beesley@arm.com>
      8aabea33
  39. 10 Oct, 2018 1 commit
  41. 02 Oct, 2018 1 commit
  43. 21 Sep, 2018 1 commit
  45. 15 Mar, 2018 2 commits
  47. 03 Aug, 2017 1 commit
    • David Cunado's avatar
      Fix to change.log · 1a3a1676
      David Cunado authored 
      

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: default avatarDavid Cunado <david.cunado@arm.com>
      1a3a1676
  49. 06 Jul, 2017 1 commit
  51. 29 Jun, 2017 2 commits