[buildstream] 02/03: doc: Document the ability to override source mirrors in user configuration

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a commit to branch tristan/mirrors
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 1ce3368247d78eef3d36f40b679f2e7c7b1b09e1
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Wed Nov 10 18:53:57 2021 +0900

    doc: Document the ability to override source mirrors in user configuration
---
 doc/source/format_project.rst |  7 ++++---
 doc/source/using_config.rst   | 38 +++++++++++++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 69b1e4c..aaece4b 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -287,9 +287,10 @@ list of URIs, e.g.
 The order that the mirrors (and the URIs therein) are consulted is in the order
 they are defined when fetching, and in reverse-order when tracking.
 
-A default mirror to consult first can be defined via
-:ref:`user config <config_default_mirror>`, or the command-line argument
-:ref:`--default-mirror <invoking_bst>`.
+The mirrors can be overridden on a per project basis using
+:ref:`user configuration <config_mirrors>`. One can also specify which mirror should
+be used first in the :ref:`user configuration <config_default_mirror>`, or using
+the  :ref:`--default-mirror <invoking_bst>` command-line argument.
 
 
 .. _project_plugins:
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
index 9f6f4db..1f5bbf3 100644
--- a/doc/source/using_config.rst
+++ b/doc/source/using_config.rst
@@ -1060,13 +1060,45 @@ modifying some low level component.
    the ``--strict`` and ``--no-strict`` command line options.
 
 
+.. _config_mirrors:
+
+Mirrors
+~~~~~~~
+Project defined :ref:`mirrors <project_essentials_mirrors>`, can be overridden
+with user configuration. This is helpful when you need to mirror all of the source
+code used by subprojects and ensure that your project can be built in perpetuity.
+
+**Example**
+
+.. code:: yaml
+
+   projects:
+     project-name:
+       mirrors:
+       - name: middle-earth
+         aliases:
+           foo:
+           - http://www.middle-earth.com/foo/1
+           - http://www.middle-earth.com/foo/2
+           bar:
+           - http://www.middle-earth.com/bar/1
+           - http://www.middle-earth.com/bar/2
+       - name: oz
+         aliases:
+           foo:
+           - http://www.oz.com/foo
+           bar:
+           - http://www.oz.com/bar
+
+
 .. _config_default_mirror:
 
 Default mirror
 ~~~~~~~~~~~~~~
-When using :ref:`mirrors <project_essentials_mirrors>`, a default mirror can
-be defined to be fetched first.
-The default mirror is defined by its name, e.g.
+When using :ref:`mirrors <project_essentials_mirrors>`, one can specify which
+mirror should be used first.
+
+**Example**
 
 .. code:: yaml