Use conda to fetch Node.js for ReadTheDocs

.readthedocs.yml

@@ -1,6 +1,4 @@
 version: 2
 
-python:
-  version: 3.8
-  install:
-    - requirements: doc/requirements.txt
+conda:
+  environment: doc/environment.yml

doc/build-with-conda.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# This script replicates the build process that ReadTheDocs uses, at least as well as it can
+
+# Get script location/path: https://stackoverflow.com/a/246128
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+# Enter repository root
+cd "$SCRIPT_DIR/.." || exit 1
+
+# Setup conda environment
+conda env create --quiet --name rtd_env --file doc/environment.yml
+conda install --yes --quiet --name rtd_env mock pillow sphinx sphinx_rtd_theme
+# Store conda bin path for later use
+CONDA_BIN=/home/docs/.conda/envs/rtd_env/bin
+"$CONDA_BIN/python" -m pip install -U --no-cache-dir recommonmark six readthedocs-sphinx-ext
+
+# Build docs
+cd doc || exit 1
+"$CONDA_BIN/python" -m sphinx -v -T -E -b html -d _build/doctrees -D language=en . _build/html

doc/conf.py

@@ -15,6 +15,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import datetime
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
@@ -61,7 +62,9 @@
 
 # General information about the project.
 project = 'remoteStorage.js'
-copyright = '2012-2020, RS Contributors'
+copyright = '2012-{current_year}, RS Contributors'.format(
+    current_year=datetime.date.today().strftime("%Y")
+)
 author = 'RS Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -185,9 +188,31 @@
      'Miscellaneous'),
 ]
 
+#
+# HACKFIX WARNING
+# TODO Remove this when RTD updates their Node.js version
+# https://github.com/readthedocs/readthedocs-docker-images/issues/107
+#
+# Manually add custom Node.js/npm from conda to PATH
+python_executable_directory = sys.path.insert(0, os.path.abspath(sys.executable + "/.."))
+os.environ["PATH"] = f"{python_executable_directory}:{os.environ['PATH']}"
+# Verify Node.js version is correct
+os.system('node --version')
+os.system('npm --version')
+
 #
 # HACKFIX WARNING
 # TODO Remove this when there is official support for pre-build steps on RTD
 # https://github.com/readthedocs/readthedocs.org/issues/6662
 #
 os.system('npm install')
+
+#
+# HACKFIX WARNING
+# TODO Remove this when RTD updates their Node.js version
+# https://github.com/readthedocs/readthedocs-docker-images/issues/107
+#
+# Manually add typedoc to PATH
+typedoc_directory = os.path.abspath('../node_modules/typedoc/bin')
+os.system(f'chmod +x {typedoc_directory}/typedoc')
+os.environ["PATH"] = f"{typedoc_directory}:{os.environ['PATH']}"

doc/contributing/docs.rst

@@ -64,6 +64,31 @@ This will start a web server, serving rendered HTML docs on `<http://localhost:8
    will need to re-run the command, or change something in a ``.rst`` file in
    order for code documentation changes to be re-built.
 
+How to build the docs using ReadTheDocs' Docker image
+-----------------------------------------------------
+
+This is useful for troubleshooting when the ReadTheDocs build is failing.
+
+Setup
+^^^^^
+
+1. `Install Docker <https://docs.docker.com/get-docker/>`_
+
+2. Pull the latest version of ``readthedocs/build`` image with the ``latest`` tag from Docker Hub::
+
+    $ docker pull readthedocs/build:latest
+
+Build
+^^^^^
+
+1. Enter a ``bash`` session while attaching this project as a volume::
+
+    $ docker run --rm -it -v ${PWD}:/app readthedocs/build:latest bash
+
+2. Run the ``build-with-conda.sh`` script to setup conda environment and build the docs like ReadTheDocs::
+
+    $ /app/doc/build-with-conda.sh
+
 .. rubric:: Footnotes
 
 .. [#f1] Every single bit helps other people! Even fixing a typo is worth a

doc/environment.yml

@@ -0,0 +1,13 @@
+name: rtd_env
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - nodejs=14.15.1
+  - pip=21.0.1
+  - python=3.8.5
+  - pip:
+    - sphinx-js >= 3.1
+    - sphinx-issues
+    - sphinx-autobuild
+    - sphinx_rtd_theme