From 136dcff9c82acf67c9bb0f5337c1c0ebfe2391bf Mon Sep 17 00:00:00 2001
From: Michael Scott Asato Cuthbert <michael.asato.cuthbert@gmail.com>
Date: Sun, 4 Jan 2026 15:17:10 -1000
Subject: [PATCH] Host our own docs alone

The project tried for over 10 years to get its docs built on readthedocs.org -- but the doc files are just too big and have too much going on with Musescore etc. to have hope that they will ever be build there.

So we'll have people read the docs at music21.org/music21docs/
---
 .readthedocs.yaml                        | 27 ------------------------
 documentation/docbuild_requirements.txt  |  3 ---
 documentation/nbvalNotebook.py           | 21 ++++++++++++++++--
 documentation/source/readthedocs_conf.py |  2 +-
 4 files changed, 20 insertions(+), 33 deletions(-)
 delete mode 100644 .readthedocs.yaml
 delete mode 100644 documentation/docbuild_requirements.txt

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
deleted file mode 100644
index ae2436da8c..0000000000
--- a/.readthedocs.yaml
+++ /dev/null
@@ -1,27 +0,0 @@
-# Read the Docs configuration file for music21
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
-version: 2
-
-# Set the OS, Python version and other tools you might need
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.13"
-
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-   configuration: documentation/source/conf.py
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
diff --git a/documentation/docbuild_requirements.txt b/documentation/docbuild_requirements.txt
deleted file mode 100644
index a2ec2689e9..0000000000
--- a/documentation/docbuild_requirements.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-# for readthedocs.io (based on requirements_dev.txt)
-nbconvert
-sphinx
diff --git a/documentation/nbvalNotebook.py b/documentation/nbvalNotebook.py
index 859049a1a1..613a8c2103 100644
--- a/documentation/nbvalNotebook.py
+++ b/documentation/nbvalNotebook.py
@@ -12,13 +12,30 @@
 import subprocess
 
 # noinspection PyPackageRequirements
-import pytest  # pylint: disable=unused-import  # noqa
+try:
+    import pytest
+except ImportError:  # pragma: no cover
+    # fail here to get a better message than file-not-found below.
+    raise ImportError(
+        'Please install pytest -- in the music21 directory run "pip install ".[dev]"'
+    )
+
 # noinspection PyPackageRequirements
-import nbval  # pylint: disable=unused-import  # noqa
+try:
+    import nbval
+except ImportError:  # pragma: no cover
+    raise ImportError(
+        'Please install nbval -- in the music21 directory run "pip install ".[dev]"'
+    )
 
 from music21 import environment
 from music21 import common
 
+if pytest is None or nbval is None:  # pragma: no cover
+    # this will never run, but it's important to use pytest and nbval variables
+    # or some modern code linters will remove the import pytest, import nbval lines.
+    raise ImportError('Please install pytest and nbval')
+
 # pytest --nbval usersGuide_15_key.ipynb --nbval-sanitize-with ../../nbval-sanitize.cfg -q
 skip = ['installJupyter.ipynb']
 
diff --git a/documentation/source/readthedocs_conf.py b/documentation/source/readthedocs_conf.py
index 601457bee2..86988e444d 100644
--- a/documentation/source/readthedocs_conf.py
+++ b/documentation/source/readthedocs_conf.py
@@ -1,4 +1,4 @@
-# Configuration file for readthedocs
+# Configuration file for docs
 # builds everything before sphinx
 
 import os