doc: Enable automatic labels for page titles

Automatic labelling of document titles is a prerequisite for
converting the format of cross-document links. Sphinx will
generate (via the enabled extension) a hidden link target for
each document title and this can be referred to later, from
another page, to link to the target.

The plugin options being used require Sphinx >= 2.0.0 so a
requirements.txt file has been added. This file is used with
the pip package manager for Python so that the correct
dependencies are installed.

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

diff --git a/docs/conf.py b/docs/conf.py
index 697b8711542127ecda16cd719184381d9d733834..64f12431bb3f4f64427717d9b8aeaced470735ad 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -23,7 +23,7 @@ release = version # We don't need these to be distinct
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -54,6 +54,9 @@ pygments_style = 'sphinx'
 with open('global_substitutions.txt', 'r') as subs:
   rst_prolog = subs.read()
 
+# Minimum version of sphinx required
+needs_sphinx = '2.0'
+
 # -- Options for HTML output -------------------------------------------------
 
 # Don't show the "Built with Sphinx" footer
@@ -75,3 +78,8 @@ html_theme_options = {
     'prev_next_buttons_location': 'both', # Top and bottom of the page
     'style_external_links': True # Display an icon next to external links
 }
+
+# -- Options for autosectionlabel --------------------------------------------
+
+# Only generate automatic section labels for document titles
+autosectionlabel_maxdepth = 1
\ No newline at end of file

diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644 (file)
index 0000000..8f95774
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=2.0.0
+sphinx-rtd-theme>=0.4.3
\ No newline at end of file