From 2b2a7678f1ba07f1d4990e3f1c055f13822bccdb Mon Sep 17 00:00:00 2001
From: Jake Stevens-Haas <37048747+Jacob-Stevens-Haas@users.noreply.github.com>
Date: Fri, 7 Apr 2023 00:10:39 -0700
Subject: [PATCH] ENH: Bump sphinx version, add pandoc version, bump RTD python
 version.

Old sphinx version spec is very old.  Both RTD and CI interpret sphinx>=2.0.0 as
5.0.3, so it seems reasonable that requiring this for developers would only
serve to prevent doc build mistakes.

Also, added pandoc as a dev requirement, because it is a requirement for
building docs.  It has an external binary requirement (pandoc) which can't be
accomodated in a requirements file.  So I added info to the readme.rst

Bump python version to 3.8 in RTD since 3.7 is approaching EOL

FWIW, was confused about pandoc so added an issue to RTFD:
https://github.com/readthedocs/readthedocs.org/issues/10229
---
 .readthedocs.yml     | 2 +-
 README.rst           | 8 ++++++++
 requirements-dev.txt | 3 ++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index ba75fe2e1..0c16f2be0 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -4,6 +4,6 @@ sphinx:
   configuration: docs/conf.py
 
 python:
-  version: 3.7
+  version: 3.8
   install:
     - requirements: requirements-dev.txt
diff --git a/README.rst b/README.rst
index d796946f9..144e9a8d4 100644
--- a/README.rst
+++ b/README.rst
@@ -204,6 +204,14 @@ you can run the following to automatically reformat your staged code
 
 Note that you will then need to re-stage any changes ``pre-commit`` made to your code.
 
+Building documentation requires [pandoc](https://pandoc.org/installing.html) as a separate install.  Once installed, run 
+
+.. code-block:: bash
+
+    python -m sphinx -TEb html -d _build/doctrees -D language=en . ./build
+
+Or check the build step in the most recent CI run or [RTD build](https://readthedocs.org/projects/pysindy/builds/).
+
 There are a number of SINDy variants and advanced functionality that would be great to implement in future releases:
 
 1. Bayesian SINDy, for instance that from Hirsh, Seth M., David A. Barajas-Solano, and J. Nathan Kutz. "Sparsifying Priors for Bayesian Uncertainty Quantification in Model Discovery." arXiv preprint arXiv:2107.02107 (2021).
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 4cf985bc4..08defeea5 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -12,7 +12,7 @@ setuptools_scm_git_archive
 jupyter
 jupytext
 notebook
-sphinx >= 2
+sphinx==5.3.0
 sphinxcontrib-apidoc
 sphinx_rtd_theme
 pre-commit
@@ -20,6 +20,7 @@ hypothesis
 nbsphinx
 jupyter_contrib_nbextensions
 pandas
+pandoc
 seaborn
 ipython
 gurobipy>=9.5.1,<10.0