doc: use RST references where appropriate

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

26 files changed, 46 insertions, 26 deletions

diff --git a/doc/device-tree.rst b/doc/device-tree.rst
index 05971942..cc9d2286 100644
--- a/doc/device-tree.rst
+++ b/doc/device-tree.rst
@@ -1,3 +1,5 @@
+.. _device-tree:
+
 Device Tree
 ===========
 
diff --git a/doc/device-tree/ibm,opal/flash.rst b/doc/device-tree/ibm,opal/flash.rst
index 28645e84..5bce76b4 100644
--- a/doc/device-tree/ibm,opal/flash.rst
+++ b/doc/device-tree/ibm,opal/flash.rst
@@ -1,3 +1,5 @@
+.. _device-tree/ibm,opal/flash:
+
 ibm,opal/flash device tree entries
 ==================================
 
diff --git a/doc/device-tree/ibm,opal/led.rst b/doc/device-tree/ibm,opal/led.rst
index 6e88b2e3..e7d80b75 100644
--- a/doc/device-tree/ibm,opal/led.rst
+++ b/doc/device-tree/ibm,opal/led.rst
@@ -1,3 +1,5 @@
+.. _device-tree/ibm,opal/leds:
+
 Service Indicators (LEDS)
 =========================
 
@@ -33,4 +35,4 @@ led-types
   Supported indicators (attention/identify/fault).
 
 These LEDs can be accessed through OPAL_LEDS_{GET/SET}_INDICATOR interfaces.
-Refer to doc/opal-api/opal-led-get-set-114-115.rst for interface details.
+Refer to :ref:`opal-api-LEDs` for interface details.
diff --git a/doc/device-tree/ibm,secureboot.rst b/doc/device-tree/ibm,secureboot.rst
index e46159ce..915ee13a 100644
--- a/doc/device-tree/ibm,secureboot.rst
+++ b/doc/device-tree/ibm,secureboot.rst
@@ -1,3 +1,5 @@
+.. _device-tree/ibm,secureboot:
+
 ibm,secureboot
 ==============
 
@@ -16,7 +18,7 @@ boot to calculate the SHA512 hash of an image only if the image is not a secure
 container or the system is not booting up in secure mode.
 
 For further information about secure boot and trusted boot please refer to
-``doc/stb.rst``.
+:ref:`stb-overview`.
 
 
 Required properties
diff --git a/doc/device-tree/nvlink.rst b/doc/device-tree/nvlink.rst
index 18b36883..a0aed4f4 100644
--- a/doc/device-tree/nvlink.rst
+++ b/doc/device-tree/nvlink.rst
@@ -1,8 +1,10 @@
+.. _device-tree/nvlink:
+
 ===========================
 Nvlink Device Tree Bindings
 ===========================
 
-See doc/nvlink.rst for general Nvlink information.
+See :ref:`nvlink` for general Nvlink information.
 
 NPU bindings: ::
 
diff --git a/doc/device-tree/tpm.rst b/doc/device-tree/tpm.rst
index eef62bb3..2f1f6a5f 100644
--- a/doc/device-tree/tpm.rst
+++ b/doc/device-tree/tpm.rst
@@ -1,3 +1,5 @@
+.. _device-tree/tpm:
+
 Trusted Platform Module (TPM)
 =============================
 
diff --git a/doc/nvlink.rst b/doc/nvlink.rst
index b6a2399b..d0359687 100644
--- a/doc/nvlink.rst
+++ b/doc/nvlink.rst
@@ -1,3 +1,5 @@
+.. _nvlink:
+
 OPAL/Skiboot Nvlink Interface Documentation
 ===========================================
 
@@ -156,4 +158,4 @@ reporting.
 Device Tree Bindings
 --------------------
 
-See doc/device-tree/nvlink.rst
+See :ref:`device-tree/nvlink`
diff --git a/doc/opal-api/opal-flash-110-111-112.rst b/doc/opal-api/opal-flash-110-111-112.rst
index c58eefdf..71ba866d 100644
--- a/doc/opal-api/opal-flash-110-111-112.rst
+++ b/doc/opal-api/opal-flash-110-111-112.rst
@@ -9,7 +9,7 @@ There are three OPAL calls for interacting with flash devices: ::
 
 Multiple flash devices are supported by OPAL - each of these calls takes an id
 parameter, which much match an ID found in the corresponding ``ibm,opal/flash@n``
-device tree node. See doc/device-tree/ibm,opal/flash.rst for details of
+device tree node. See :ref:`device-tree/ibm,opal/flash` for details of
 the device tree bindings.
 
 All operations on the flash device must be aligned to the block size of the
diff --git a/doc/opal-api/opal-get-msg-85.rst b/doc/opal-api/opal-get-msg-85.rst
index 7e65b417..2cc9307e 100644
--- a/doc/opal-api/opal-get-msg-85.rst
+++ b/doc/opal-api/opal-get-msg-85.rst
@@ -1,8 +1,7 @@
 OPAL_GET_MSG
 ============
 
-OPAL_GET_MSG will get the next pending OPAL Message (see
-doc/opal-api/opal-messages.rst).
+OPAL_GET_MSG will get the next pending OPAL Message (see :ref:`opal-messages`).
 
 Parameters: ::
 
diff --git a/doc/opal-api/opal-handle-interrupt.rst b/doc/opal-api/opal-handle-interrupt.rst
index 42b26e9e..ce2028fc 100644
--- a/doc/opal-api/opal-handle-interrupt.rst
+++ b/doc/opal-api/opal-handle-interrupt.rst
@@ -24,4 +24,4 @@ The ``OPAL_HANDLE_INTERRUPT`` call takes two parameters, one input and one outpu
 
 The host OS should then handle any outstanding events.
 
-See doc/opal-api/opal-poll-events.rst for documentation on events.
+See :ref:`OPAL_POLL_EVENTS` for documentation on events.
diff --git a/doc/opal-api/opal-led-get-set-114-115.rst b/doc/opal-api/opal-led-get-set-114-115.rst
index 85656bf1..c0d874ea 100644
--- a/doc/opal-api/opal-led-get-set-114-115.rst
+++ b/doc/opal-api/opal-led-get-set-114-115.rst
@@ -1,3 +1,5 @@
+.. _opal-api-LEDs:
+
 Service Indicators (LEDS)
 =========================
 
@@ -19,6 +21,7 @@ Different types of indicators handled by LED code:
       Indicates there is a problem with the FRU or resource at the
       location with which the indicator is associated.
 
+All LEDs are defined in the device tree (see :ref:`device-tree/ibm,opal/leds`).
 
 LED Design
 ----------
diff --git a/doc/opal-api/opal-messages.rst b/doc/opal-api/opal-messages.rst
index dfb74e4c..e4e813aa 100644
--- a/doc/opal-api/opal-messages.rst
+++ b/doc/opal-api/opal-messages.rst
@@ -1,3 +1,5 @@
+.. _opal-messages:
+
 OPAL_MESSAGE
 ============
 
diff --git a/doc/opal-api/opal-poll-events.rst b/doc/opal-api/opal-poll-events.rst
index c70d7f0f..71ca21bf 100644
--- a/doc/opal-api/opal-poll-events.rst
+++ b/doc/opal-api/opal-poll-events.rst
@@ -1,3 +1,5 @@
+.. _OPAL_POLL_EVENTS:
+
 OPAL_POLL_EVENTS
 ================
 
diff --git a/doc/opal-spec.rst b/doc/opal-spec.rst
index 770b605c..ae1a1a42 100644
--- a/doc/opal-spec.rst
+++ b/doc/opal-spec.rst
@@ -173,8 +173,7 @@ under other platforms. For example, a single Linux kernel can be built to boot
 under OPAL and under PowerVM or qemu pseries machine type.
 
 The root node of the device tree MUST have compatible = "ibm,powernv".
-See doc/device-tree.rst for more details
-[TODO: make doc/device-tree.rst better]
+See :ref:`device-tree` for more details.
 
 The presence of the "/ibm,opal" entry in the device tree signifies running
 under OPAL. Additionally, the "/ibm,opal" node MUST have a compatibile property
@@ -210,7 +209,7 @@ about the firmware environment.
 
 The version property is a textual representation of the OPAL version.
 For example, it may be "skiboot-4.1" or other versioning described
-in more detail in doc/versioning.rst
+in more detail in :ref:`versioning`.
 
 
 OPAL log
diff --git a/doc/release-notes/skiboot-5.2.0-rc1.rst b/doc/release-notes/skiboot-5.2.0-rc1.rst
index 7ec129d1..eb50891b 100644
--- a/doc/release-notes/skiboot-5.2.0-rc1.rst
+++ b/doc/release-notes/skiboot-5.2.0-rc1.rst
@@ -10,7 +10,7 @@ released August 17th, 2015.
 skiboot-5.2.0-rc1 contains all bug fixes as of skiboot-5.1.13.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 The current plan is to release skiboot-5.2.0 mid-March 2016, with a focus on
 bug fixing for future 5.2.0-rc releases.
diff --git a/doc/release-notes/skiboot-5.2.0-rc2.rst b/doc/release-notes/skiboot-5.2.0-rc2.rst
index 49d6f64f..5207522e 100644
--- a/doc/release-notes/skiboot-5.2.0-rc2.rst
+++ b/doc/release-notes/skiboot-5.2.0-rc2.rst
@@ -10,7 +10,7 @@ released August 17th, 2015.
 skiboot-5.2.0-rc2 contains all bug fixes as of skiboot-5.1.14.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 The current plan is to release skiboot-5.2.0 mid-March 2016, with a focus on
 bug fixing for future 5.2.0-rc releases (if any - I hope this will be the last)
diff --git a/doc/release-notes/skiboot-5.2.0.rst b/doc/release-notes/skiboot-5.2.0.rst
index 8940f942..28d977d9 100644
--- a/doc/release-notes/skiboot-5.2.0.rst
+++ b/doc/release-notes/skiboot-5.2.0.rst
@@ -10,7 +10,7 @@ first released August 17th, 2015.
 skiboot-5.2.0 contains all bug fixes as of skiboot-5.1.15.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Changes since rc2
 -----------------
diff --git a/doc/release-notes/skiboot-5.2.1.rst b/doc/release-notes/skiboot-5.2.1.rst
index 4782ee6b..877a2fd3 100644
--- a/doc/release-notes/skiboot-5.2.1.rst
+++ b/doc/release-notes/skiboot-5.2.1.rst
@@ -10,7 +10,7 @@ first released August 17th, 2015.
 skiboot-5.2.1 contains all bug fixes as of skiboot-5.1.15.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Changes
 -------
diff --git a/doc/release-notes/skiboot-5.2.2.rst b/doc/release-notes/skiboot-5.2.2.rst
index f8eeecd1..0de03726 100644
--- a/doc/release-notes/skiboot-5.2.2.rst
+++ b/doc/release-notes/skiboot-5.2.2.rst
@@ -14,7 +14,7 @@ one bug fix targeted at P8NVL systems, notably the Garrison platform.
 skiboot-5.2.2 contains all bug fixes as of skiboot-5.1.16.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Over skiboot-5.2.1, the following fixes are included:
 
diff --git a/doc/release-notes/skiboot-5.2.3.rst b/doc/release-notes/skiboot-5.2.3.rst
index 99273640..6ed30acd 100644
--- a/doc/release-notes/skiboot-5.2.3.rst
+++ b/doc/release-notes/skiboot-5.2.3.rst
@@ -15,7 +15,7 @@ frequency tables, which could lead to no CPU frequency scaling.
 skiboot-5.2.3 contains all bug fixes as of skiboot-5.1.16.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Over skiboot-5.2.2, the following fixes are included:
 
diff --git a/doc/release-notes/skiboot-5.2.4.rst b/doc/release-notes/skiboot-5.2.4.rst
index 844e02b3..43c47023 100644
--- a/doc/release-notes/skiboot-5.2.4.rst
+++ b/doc/release-notes/skiboot-5.2.4.rst
@@ -14,7 +14,7 @@ build improvements for the pflash utility.
 skiboot-5.2.4 contains all bug fixes as of skiboot-5.1.16.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Over skiboot-5.2.3, the following fixes are included:
 
diff --git a/doc/release-notes/skiboot-5.2.5.rst b/doc/release-notes/skiboot-5.2.5.rst
index 8e4a049b..3c1e8c8e 100644
--- a/doc/release-notes/skiboot-5.2.5.rst
+++ b/doc/release-notes/skiboot-5.2.5.rst
@@ -6,7 +6,7 @@ skiboot-5.2.5 was released on Thursday July 28th, 2016.
 skiboot-5.2.5 contains all bug fixes as of skiboot-5.1.17.
 
 This is the second release that will follow the (now documented) Skiboot
-stable rules - see doc/stable-skiboot-rules.rst.
+stable rules - see :ref:`stable-rules`.
 
 Over skiboot-5.2.4, the following fixes are included:
 
diff --git a/doc/release-notes/skiboot-5.3.0-rc1.rst b/doc/release-notes/skiboot-5.3.0-rc1.rst
index b110e38d..ca622b0b 100644
--- a/doc/release-notes/skiboot-5.3.0-rc1.rst
+++ b/doc/release-notes/skiboot-5.3.0-rc1.rst
@@ -10,8 +10,7 @@ released March 16th 2016.
 skiboot-5.3.0-rc1 contains all bug fixes as of skiboot-5.1.16
 and skiboot-5.2.4 (the existing stable releases).
 
-For how the skiboot stable releases work, see doc/stable-skiboot-rules.rst
-in the skiboot source repository.
+For how the skiboot stable releases work, see :ref:`stable-rules`.
 
 The current plan is to release skiboot-5.3.0 August 1st 2016.
 
diff --git a/doc/release-notes/skiboot-5.3.1.rst b/doc/release-notes/skiboot-5.3.1.rst
index f5e87fe9..7aecb844 100644
--- a/doc/release-notes/skiboot-5.3.1.rst
+++ b/doc/release-notes/skiboot-5.3.1.rst
@@ -9,7 +9,7 @@ skiboot (first released with 5.3.0 on August 2nd, 2016).
 Skiboot 5.3.1 replaces skiboot-5.3.0 as the current stable version. It contains
 a few minor bug fixes.
 
-This release follows the Skiboot stable rules, see doc/stable-skiboot-rules.rst.
+This release follows the Skiboot stable rules, see :ref:`stable-rules`.
 
 Over skiboot-5.3.0, the following fixes are included:
 
diff --git a/doc/stb.rst b/doc/stb.rst
index 2b443705..c62b574c 100644
--- a/doc/stb.rst
+++ b/doc/stb.rst
@@ -69,16 +69,16 @@ boot support for a platform:
 
 First, ``stb_init()`` must be called to initialize libstb. Basically, it reads both
 secure mode and trusted mode flags and loads drivers accordingly. In P8, secure
-mode and trusted mode are read from the *ibm,secureboot* device tree node,
-which is documented in ``doc/device-tree/ibm,secureboot.rst``
+mode and trusted mode are read from the *ibm,secureboot* device tree node (see
+:ref:`device-tree/ibm,secureboot`).
 
 If either secure mode or trusted mode is on, ``stb_init()`` loads a driver (romcode
 driver) to access the verification and SHA512 functions provided by the code
 stored in the secure ROM at manufacture time. Both secure boot and trusted boot
 depends on the romcode driver to access the ROM code. If trusted mode is on,
 ``stb_init()`` loads a TPM device driver compatible with the tpm device tree node
-and also initializes the existing event log in skiboot. The tpm device tree
-node is documented in ``doc/device-tree/tpm.rst``.
+and also initializes the existing event log in skiboot. For device tree bindings
+for the TPM, see :ref:`device-tree/tpm`.
 
 Once libstb is initialized in the platform, ``sb_verify()`` and ``tb_measure()`` can
 used as shown in the example above to respectively verify and measure images
diff --git a/doc/versioning.rst b/doc/versioning.rst
index 64ccc2c7..b802e06d 100644
--- a/doc/versioning.rst
+++ b/doc/versioning.rst
@@ -1,3 +1,5 @@
+.. _versioning:
+
 Versioning Scheme of skiboot
 ============================