From 2093bbb3f00f00b63a76e85be3529efdcffd0da0 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Mon, 26 Feb 2024 18:05:19 +0000
Subject: [PATCH] docs: Fix issues in readthedocs builds. (#800)

Add required .readthedocs.yml and docs/requirements.txt files.

Fixes error:
    NameError: name 'html_theme' is not defined

Also fixes a couple of issues highlighted by the sphinx build
output.
---
 .readthedocs.yaml     | 14 ++++++++++++++
 docs/conf.py          | 19 +++----------------
 docs/index.rst        |  1 -
 docs/neopixel.rst     |  1 +
 docs/requirements.txt |  2 ++
 5 files changed, 20 insertions(+), 17 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100644 docs/requirements.txt

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 000000000..90e616e92
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,14 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/docs/conf.py b/docs/conf.py
index 8450fa908..b945bdeaf 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx_rtd_theme',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -53,7 +54,7 @@
 
 # General information about the project.
 project = u'BBC micro:bit MicroPython'
-copyright = u'2015-2022, Multiple authors'
+copyright = u'2015-2024, Multiple authors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -110,7 +111,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -338,17 +339,3 @@
 
 # If false, no index is generated.
 #epub_use_index = True
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
-
-# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-# otherwise, readthedocs.org uses their theme by default, so no need to specify it
diff --git a/docs/index.rst b/docs/index.rst
index b49c12182..43e2b2ee2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -93,7 +93,6 @@ Projects related to MicroPython on the BBC micro:bit include:
    :maxdepth: 2
    :caption: Developer Guide
 
-   devguide/installation
    devguide/flashfirmware
    devguide/repl
    devguide/hexformat
diff --git a/docs/neopixel.rst b/docs/neopixel.rst
index c2b274573..4ae7464e9 100644
--- a/docs/neopixel.rst
+++ b/docs/neopixel.rst
@@ -28,6 +28,7 @@ art and games such as the demo shown below.
 
 .. image:: neopixel.gif
    :alt: Neopixel flexible tile
+
 Image attribution: `adafruit flexible Neopixel matrix <https://www.adafruit.com/product/2547>`_
 
 To connect a strip of neopixels you'll need to attach the micro:bit as shown
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 000000000..51f9daad0
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx<8
+sphinx_rtd_theme<2