docs: warning-free sphinx build + regenerate getting_started notebook#260
Merged
Conversation
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
- conf.py: put repo root on sys.path so autodoc imports ptsa regardless of CWD/install; set language='en'; drop the deprecated get_html_theme_path(); filter the readers FutureWarning; suppress the intentional toc.excluded warning for the notebooks-only examples toctree. - add docs/_static/ (html_static_path entry that didn't exist). - concat.py: reformat the concat() docstring as valid reST (blank lines before nested bullet lists, aligned continuations) — fixes 9 docutils Unexpected-indentation / block-quote warnings. Sphinx build is now warning-free; the 34 sybil doc-example tests still pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Re-executed the synthetic getting-started notebook against the modern stack (numpy 2.x / pandas 3.x / xarray 2026.x) so its stored outputs match current PTSA, and normalized its kernelspec to python3. Add tests/test_notebooks.py, which executes the notebook end-to-end via nbclient against a kernel pinned to the test interpreter, so notebook API drift fails pytest the way sybil already guards docs/*.rst. It skips cleanly when the notebook toolchain (nbclient/ipykernel/ matplotlib) is absent. The legacy py2/rhino eeg.ipynb is left as-is and not executed. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add a 'Building the documentation' section: the sphinx toolchain, the sphinx-build command, the PTSA_DOCS_BUILD_NOTEBOOKS=1 + pandoc opt-in for notebooks, and a note that docs/html/ is a generated GH-Pages artifact (regenerated via maint/build_docs.py at publish time). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation polish, split out from the build-modernization PR (#259)
so the build PR stays focused. Stacked on top of #259 — until #259
merges to master, this PR's diff will also show #259's commits; once
#259 lands, it narrows to the two docs commits below.
sys.path for autodoc,
language='en', drop deprecatedget_html_theme_path(), filter the readers FutureWarning, suppress theintentional
toc.excludednotebooks warning; adddocs/_static/;reformat the
concat()docstring as valid reST.xarray 2026.x) with a portable
python3kernelspec, plustests/test_notebooks.py, which executes it end-to-end via nbclient(skips cleanly where the notebook toolchain is absent). The legacy
py2/rhino
eeg.ipynbis left as-is.Not included: a regenerated
docs/html/snapshot — that GH-Pagesartifact is rebuilt at deploy time via
maint/build_docs.py(now thatthe build is warning-free).
Validation
sphinx-buildofdocs/: 0 warnings.tests/test_notebooks.py: passeslocally (numpy 2.4 / pandas 3.0 / xarray 2026.4).
🤖 Generated with Claude Code