Fix docs

[kavanase]

From the recent PR merge, the docs build failed again because the sphinx_rtd_theme requirement is missing (see https://readthedocs.org/projects/nequip/builds/24124155/).

I checked by using the same build code on my local as used by RTD, with a fresh virtual environment, and just adding this requirement then fixes the issue and it all builds fine.

[kavanase]

Code showing this fixing the issue:

python -m sphinx -T -b html -d _build/doctrees -D language=en . html
Running Sphinx v7.3.7

Traceback (most recent call last):
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages/sphinx/registry.py", line 453, in load_extension
    mod = import_module(extname)
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 984, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'sphinx_rtd_theme'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages/sphinx/cmd/build.py", line 332, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages/sphinx/application.py", line 229, in __init__
    self.setup_extension(extension)
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages/sphinx/application.py", line 402, in setup_extension
    self.registry.load_extension(self, extname)
  File "/Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages/sphinx/registry.py", line 456, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')

Extension error:
Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')
❯ pip install sphinx_rtd_theme
Collecting sphinx_rtd_theme
  Using cached sphinx_rtd_theme-2.0.0-py2.py3-none-any.whl.metadata (4.4 kB)
Requirement already satisfied: sphinx<8,>=5 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx_rtd_theme) (7.3.7)
Requirement already satisfied: docutils<0.21 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx_rtd_theme) (0.20.1)
Collecting sphinxcontrib-jquery<5,>=4 (from sphinx_rtd_theme)
  Downloading sphinxcontrib_jquery-4.1-py2.py3-none-any.whl.metadata (2.6 kB)
Requirement already satisfied: sphinxcontrib-applehelp in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.0.8)
Requirement already satisfied: sphinxcontrib-devhelp in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.0.6)
Requirement already satisfied: sphinxcontrib-jsmath in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.0.1)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.0.5)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.9 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.1.10)
Requirement already satisfied: sphinxcontrib-qthelp in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.0.7)
Requirement already satisfied: Jinja2>=3.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (3.1.3)
Requirement already satisfied: Pygments>=2.14 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.17.2)
Requirement already satisfied: snowballstemmer>=2.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.2.0)
Requirement already satisfied: babel>=2.9 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.14.0)
Requirement already satisfied: alabaster~=0.7.14 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (0.7.16)
Requirement already satisfied: imagesize>=1.3 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (1.4.1)
Requirement already satisfied: requests>=2.25.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.31.0)
Requirement already satisfied: packaging>=21.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (24.0)
Requirement already satisfied: importlib-metadata>=4.8 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (7.1.0)
Requirement already satisfied: tomli>=2 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from sphinx<8,>=5->sphinx_rtd_theme) (2.0.1)
Requirement already satisfied: zipp>=0.5 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from importlib-metadata>=4.8->sphinx<8,>=5->sphinx_rtd_theme) (3.18.1)
Requirement already satisfied: MarkupSafe>=2.0 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from Jinja2>=3.0->sphinx<8,>=5->sphinx_rtd_theme) (2.1.5)
Requirement already satisfied: charset-normalizer<4,>=2 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from requests>=2.25.0->sphinx<8,>=5->sphinx_rtd_theme) (3.3.2)
Requirement already satisfied: idna<4,>=2.5 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from requests>=2.25.0->sphinx<8,>=5->sphinx_rtd_theme) (3.7)
Requirement already satisfied: urllib3<3,>=1.21.1 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from requests>=2.25.0->sphinx<8,>=5->sphinx_rtd_theme) (2.2.1)
Requirement already satisfied: certifi>=2017.4.17 in /Users/kavanase/miniconda3/envs/nequip_docs/lib/python3.9/site-packages (from requests>=2.25.0->sphinx<8,>=5->sphinx_rtd_theme) (2024.2.2)
Downloading sphinx_rtd_theme-2.0.0-py2.py3-none-any.whl (2.8 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.8/2.8 MB 13.5 MB/s eta 0:00:00
Downloading sphinxcontrib_jquery-4.1-py2.py3-none-any.whl (121 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 121.1/121.1 kB 16.7 MB/s eta 0:00:00
Installing collected packages: sphinxcontrib-jquery, sphinx_rtd_theme
Successfully installed sphinx_rtd_theme-2.0.0 sphinxcontrib-jquery-4.1
❯ python -m sphinx -T -b html -d _build/doctrees -D language=en . html
Running Sphinx v7.3.7
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 16 source files that are out of date
updating environment: [new config] 16 added, 0 changed, 0 removed
reading sources... [100%] introduction/intro
/Users/kavanase/Packages/nequip/docs/errors/errors.md:4: WARNING: Non-consecutive header level increase; H1 to H4 [myst.header]
/Users/kavanase/Packages/nequip/docs/errors/errors.md:11: WARNING: Non-consecutive header level increase; H1 to H4 [myst.header]
/Users/kavanase/Packages/nequip/docs/errors/errors.md:18: WARNING: Non-consecutive header level increase; H1 to H4 [myst.header]
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/kavanase/Packages/nequip/docs/howto/migrate.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] introduction/intro
/Users/kavanase/Packages/nequip/docs/errors/errors.md:6: WARNING: Pygments lexer name 'txt' is not known
/Users/kavanase/Packages/nequip/docs/howto/dataset.rst:53: WARNING: Pygments lexer name 'extxyz' is not known
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 9 warnings.

The HTML pages are in html.
❯ ls html/
 _sources   api           errors   howto          introduction   genindex.html   objects.inv   searchindex.js
 _static    commandline   faq      integrations   cite.html      index.html      search.html
❯ open html/index.html

This is what the new, fixed build docs look like:

Current live docs:

[kavanase]

@Linux-cpp-lisp docs now building without issue btw: https://nequip.readthedocs.io/en/develop/

This is on the develop branch, so the main (latest) docs build still fails, which is the badge shown on the repo README

[Linux-cpp-lisp]

Got it, thanks Sean!