docs: Fix issues in readthedocs builds. (bbcmicrobit#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.

Author: microbit-carlos

.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

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

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

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

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx<8
+sphinx_rtd_theme<2