Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document tagged versions as well as latest main #199

Open
adigitoleo opened this issue Jun 17, 2024 · 2 comments
Open

Document tagged versions as well as latest main #199

adigitoleo opened this issue Jun 17, 2024 · 2 comments
Labels
documentation Improvements or additions to documentation
Milestone
Beta release

Comments

@adigitoleo
Copy link
Member

Pdoc needs some extra steps for documenting multiple versions. Luckily, it seems someone has already come up with a way to do it: mitmproxy/pdoc#470 (comment). We can use that to either document the most recent tag + main HEAD or all tags + main HEAD.
@adigitoleo adigitoleo added the documentation Improvements or additions to documentation label Jun 17, 2024
adigitoleo added a commit that referenced this issue Aug 1, 2024
@adigitoleo
build: Only deploy docs for latest tag
e9029aa 
This brings us one step towards having docs for every tagged version.
For now (after the next tag push) there should only be one website for
the latest tagged version. Earlier versions can be built offline.
Progress to #199.

In any case, it is better than the current situation: html documentation
is being deployed for every single push on `main`, and the docs website
did not indicate a version number anywhere. With these GH workflow
adjustments, the docs should still be _built_ for each PR/push to main,
allowing to catch errors in the documentation setup as they arise,
but the html pages will not deployed to GitHub Pages if there is no tag.
The version (obtained from `git describe`) is also indicated clearly
on the website landing page and in the API docs sidebar footer.

Related things that I rolled in here:
- new make target to build docs (simply `make html` in the action spec)
- favicon and proper branding (multiple resolutions of logo)
- removed a duplicated sentence from the README
- `docs/template/README.md` to explain how to maintain the template
- fixed `rm -r` -> `rm -rf` in `make clean` recipe
@adigitoleo adigitoleo mentioned this issue Aug 1, 2024
Merged
@adigitoleo
Copy link
Member Author

adigitoleo commented Aug 7, 2024 •
edited
Loading

Documentation should include the version number next time it builds on top of a tag (after #207). Need to test this with a v0.1.0-rc1 tag soon (not necessary to have a new PyPI release until v0.1.0 proper, but could be nice).

  • Ensure that documentation website includes version number (9b58702)
  • Modify docs.yml to build for all tags, not just latest
  • Add version selector to the website (javascript, see linked comment above) (d753903)

I don't think we need to worry about also building docs for HEAD on main, building them offline is very simple (c.f. Sphinx, Doxygen, ...)

@adigitoleo adigitoleo added this to the Beta release milestone Aug 7, 2024
@adigitoleo
Copy link
Member Author

We don't want to store built docs for earlier versions in the repository; at the same time, doing git checkout on an earlier version and trying to build the docs is not likely to just work, because (transient) dependencies may have been updated since then (and I don't want to pin fixed versions of all dependencies for each PyDRex version). For example, trying to build the docs for v0.0.1 again now fails because we had NumPy 2.0 come out in the meantime.

Part of the problem is that building the docs with pdoc fundamentally requires importing the package (dynamic analysis), but I think that is the same for most Python documentation builders. The options here are: (1) forget about building docs for old versions, since we probably won't be maintaining them with backported patches for such a project or (2) store the built docs for older versions in some persistent online storage somewhere and re-download them into subdirectories of html/ when deploying the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
Beta release
Development

No branches or pull requests
1 participant
@adigitoleo