Skip to content

Overhaul sphinx docs - #920

Merged
thehrh merged 7 commits into
masterfrom
enhancement/sphinx_docs
Apr 17, 2026
Merged

thehrh merged 7 commits into
masterfrom
enhancement/sphinx_docs

Conversation

@thehrh

@thehrh thehrh commented Apr 1, 2026 •

Copy link
Copy Markdown
Collaborator

The current PISA html docs only contain the auto-generated Python API references/indexes.

In addition to introducing a different theme, this PR includes various of our own resources (selection of important markdown files, jupyter notebooks) in the html docs, as well as a changelog generated from PISA's releases. New sphinx extensions need to be installed to achieve this, as the modified list of develop packages in setup.py reveals.

I've uploaded the docs built from this branch to https://user-web.icecube.wisc.edu/~tehrhardt/pisa_docs so that you can take a look first.

@thehrh thehrh added this to the 4.3 milestone Apr 1, 2026
@thehrh
thehrh requested a review from JanWeldert April 15, 2026 16:12
@thehrh

thehrh commented Apr 15, 2026

Copy link
Copy Markdown
Collaborator Author

In my opinion, it isn't too important to have the automatically generated reST files (docs/source/pisa.stages.xsec.rst and so on, by sphinx-apidoc, which for some reason now produces a changed directive order) in here—or to keep them updated as code structure changes:

  • the documentation workflow generates an up-to-date list of reST files before building the HTML docs anyway
  • anyone building the docs locally on their machine can quickly run sphix-apidoc themselves also; only if they don't and code structure has changed compared to whatever the list of reST files in the master branch represents will they end up with outdated sphinx docs

@thehrh
thehrh merged commit 52f1c4d into master Apr 17, 2026
@thehrh
thehrh deleted the enhancement/sphinx_docs branch April 17, 2026 13:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants