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 0597194..cc9d228 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 28645e8..5bce76b 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 6e88b2e..e7d80b7 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 e46159c..915ee13 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 18b3688..a0aed4f 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 eef62bb..2f1f6a5 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 b6a2399..d035968 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 c58eefd..71ba866 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 7e65b41..2cc9307 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 42b26e9..ce2028f 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 85656bf..c0d874e 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 dfb74e4..e4e813a 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 c70d7f0..71ca21b 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 770b605..ae1a1a4 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 7ec129d..eb50891 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 49d6f64..5207522 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 8940f94..28d977d 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 4782ee6..877a2fd 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 f8eeecd..0de0372 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 9927364..6ed30ac 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 844e02b..43c4702 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 8e4a049..3c1e8c8 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 b110e38..ca622b0 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 f5e87fe..7aecb84 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 2b44370..c62b574 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 64ccc2c..b802e06 100644
--- a/doc/versioning.rst
+++ b/doc/versioning.rst
@@ -1,3 +1,5 @@
+.. _versioning:
+
 Versioning Scheme of skiboot
 ============================