Skip to content

Overhaul sphinx docs#920

Open
thehrh wants to merge 7 commits intomasterfrom
enhancement/sphinx_docs
Open

Overhaul sphinx docs#920
thehrh wants to merge 7 commits intomasterfrom
enhancement/sphinx_docs

Conversation

@thehrh
Copy link
Copy Markdown
Collaborator

@thehrh thehrh commented Apr 1, 2026

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
Copy link
Copy Markdown
Collaborator Author

thehrh commented Apr 15, 2026

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

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.

1 participant