Add comment for doc-requirements to avoid future issues
+# Order matters:
+# - myst-parser depends on "sphinx>=2,<4"
+# - pydata-sphinx-theme depends on "sphinx"
+# - sphinx-copybutton depends on "sphinx>=1.8"
+#
+# Listing either pydata-sphinx-theme or sphinx-copybutton first will make the
+# myst-parser constraints on sphinx be ignored, so myst-parser should go
+# first. This is only relevant if sphinx==1.* is already installed in the
+# environment, which it is on ReadTheDocs.
+
# documentation specific extra packages
myst-parser
pydata-sphinx-theme
@@ -5,6 +15,7 @@ sphinx-copybutton
traitlets
pandas
ruamel.yaml
+
# install BinderHub dependencies. We manually list them here because some
# dependencies (like pycurl) can't be installed on ReadTheDocs and aren't
# needed to build the docs.
