Add configuration file for readthedocs

[oskooi]

Adds a configuration file for readthedocs to the source tree. This should improve reproducibility of the build environments which hopefully fixes the random build failures we experience occasionally (such as the current failure). Note that the YAML file must have a .yaml rather than .yml extension (even though the other YAML files in the source tree use .yml).

Also, as described in #1734 (comment), mkdocs does not support building pdf or epub versions of the docs (only html is supported) and so the formats option is removed from mkdocs.yml because it does not do anything.

[stevengj]

Still getting an error:

Traceback (most recent call last):
  File "/home/docs/.pyenv/versions/3.7.9/lib/python3.7/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/home/docs/.pyenv/versions/3.7.9/lib/python3.7/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/__main__.py", line 16, in <module>
    from mkdocs import config                                 # noqa: E402
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/config/__init__.py", line 2, in <module>
    from mkdocs.config.defaults import DEFAULT_SCHEMA
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/config/defaults.py", line 1, in <module>
    from mkdocs.config import config_options
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 7, in <module>
    from mkdocs import utils, theme, plugins
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/theme.py", line 6, in <module>
    from mkdocs.utils import filters
  File "/home/docs/checkouts/readthedocs.org/user_builds/meep/envs/latest/lib/python3.7/site-packages/mkdocs/utils/filters.py", line 11, in <module>
    @jinja2.contextfilter
AttributeError: module 'jinja2' has no attribute 'contextfilter'

[stevengj]

Same as readthedocs/readthedocs.org#9064

[stevengj]

In particular, we might try: https://github.com/wishopt/ReFramed/commit/a9338b6205e1050b8f12b3590f604baa8b2f1992

[oskooi]

Looks like this broken dependency was fixed in mkdocs 1.2.4 in Mar. 2022. However, we should be using version 1.4.3 which does not require pinning jinja2 as we are doing now. The build error could mean that requirements.txt is not actually being used for the build. To confirm this, we would need to know from the log what version of mkdocs is being used. My guess is it is likely < 1.2.4.

(Note that this error is consistent with .readthedocs.yaml which pins the Python version to 3.10 but yet the build log shows Python 3.7. The configuration files .readthedocs.yaml and docs/requirements checked into this repo both seem to be ignored.)