Skip to content

fix readthedocs build - #100

Open
orbeckst wants to merge 5 commits into
mainfrom
update-rtd
Open

fix readthedocs build#100
orbeckst wants to merge 5 commits into
mainfrom
update-rtd

Conversation

@orbeckst

@orbeckst orbeckst commented Jul 23, 2026

Copy link
Copy Markdown
Member

Fixes #99 and #75

Changes made in this Pull Request:

  • RTD config update
    • use os = ubuntu-lts-latest
    • use tools.python = "miniforge3-latest"
  • bump sphinx to >= 7.2.0
    • required for making it work under Python 3.14 (otherwise error due ast.Str missing)
    • removed pin on myst-parser (required for sphinx>=7)
  • fixed the pydantic example (would not pass with pydantic > 1)

PR Checklist

  • Tests?
  • Docs?
  • CHANGELOG updated?
  • Issue raised/referenced?

@orbeckst

Copy link
Copy Markdown
Member Author

New errors:

/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/docutils/utils/math/latex2mathml.py:954: SyntaxWarning: "\i" is an invalid escape sequence. Such sequences will not work in the future. Did you mean "\\i"? A raw string is also an option.
  node = parse_latex_math(node, '\int\dotsi\int')
Running Sphinx v6.2.1
making output directory... done
[autosummary] generating autosummary for: additional_samples.rst, autodoc_pydantic_example.rst, change-log.rst, customization.rst, index.rst, license.rst, mdanalysis.rst, notebook.ipynb, numpydoc_example.rst, primer.rst, pymethod.rst, rst-cheatsheet/rst-cheatsheet.rst, specimen.rst, subpage/index.rst, subpage/second-subsubpage.rst, subpage/subsubpage.rst, writing-references.rst
Matplotlib is building the font cache; this may take a moment.
Failed to import pydantic_example.
Possible hints:
* KeyError: 'pydantic_example'
* PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package. See https://docs.pydantic.dev/2.13/migration/#basesettings-has-moved-to-pydantic-settings for more details.

@orbeckst

Copy link
Copy Markdown
Member Author

Additional (?) error:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/__init__.py", line 125, in analyze
    parser.parse()
    ~~~~~~~~~~~~^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 554, in parse
    self.parse_comments()
    ~~~~~~~~~~~~~~~~~~~^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 561, in parse_comments
    picker.visit(tree)
    ~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 514, in generic_visit
    self.visit(item)
    ~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 437, in visit_ClassDef
    self.visit(child)
    ~~~~~~~~~~^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 452, in visit_FunctionDef
    self.visit(child)
    ~~~~~~~~~~^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 514, in generic_visit
    self.visit(item)
    ~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 426, in visit_Try
    self.visit(subnode)
    ~~~~~~~~~~^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 321, in visit
    super().visit(node)
    ~~~~~~~~~~~~~^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/ast.py", line 506, in visit
    return visitor(node)
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/parser.py", line 403, in visit_Expr
    isinstance(node.value, ast.Str)):
                           ^^^^^^^
AttributeError: module 'ast' has no attribute 'Str'

...


Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/sphinx/pycode/__init__.py", line 141, in analyze
    raise PycodeError(f'parsing {self.srcname!r} failed: {exc!r}') from exc
sphinx.errors.PycodeError: parsing '/home/docs/checkouts/readthedocs.org/user_builds/mdanalysis-sphinx-theme/conda/100/lib/python3.14/site-packages/MDAnalysis/core/topologyattrs.py' failed: AttributeError("module 'ast' has no attribute 'Str'")

- fix #75
- avoids error of missing ast.Str in Python 3.14
- verified that 7.2.0 builds the docs
@orbeckst orbeckst linked an issue Jul 23, 2026 that may be closed by this pull request
orbeckst added 2 commits July 22, 2026 19:31
The historical pin of myst-parser=~1.0 prevents modern sphinx>=7 and fails on RTD.
Letting myst-parser to float freely does not affect local builds.
The package is not listed in pyproject.toml so should not adversely affect downstream users.
@orbeckst
orbeckst requested a review from lilyminium July 23, 2026 02:38
@orbeckst

Copy link
Copy Markdown
Member Author

@lilyminium are you happy with this upgrade?

@orbeckst orbeckst mentioned this pull request Jul 23, 2026
4 tasks
@orbeckst orbeckst changed the title updated readthedocs config fix readthedocs build Jul 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

RTD build fails New bugfix release w/ sphinx 7 support

2 participants