search

nexusformat / definitions

Definitions of the NeXus Standard File Structure and Contents
https://manual.nexusformat.org/
Other
26 stars 56 forks source link

provide HTML documentation for any version of the NeXus standard #1021

Open prjemian opened 2 years ago

prjemian commented 2 years ago

It would be nice to see the HTML documentation for any version of the NeXus standard (as much as may be made available). An example is the documentation of Python as shown: image

This would be in keeping with the current release procedure (step 11) and benefit the community.

Presently, a PDF copy of a tag is committed to the repository: https://github.com/nexusformat/definitions/tree/main/legacy_docs

Originally posted by @prjemian in https://github.com/nexusformat/definitions/issues/1016#issuecomment-1061073169

PeterC-DLS commented 2 years ago

So there's a sphinx extension called sphinx-multiversion and there's an example of a PR from another project

prjemian commented 2 years ago

Work will not be complete for this milestone, moving to next milestone.

prjemian commented 2 years ago

The PyData Sphinx theme documentation provides this feature with their Sphinx-built docs, using switcher.json. A search of the source repository provides indications how the feature is provided.

PeterC-DLS commented 2 years ago

You mean the version switcher

prjemian commented 2 years ago

What changes are needed to our publishing workflow to retain different versions of the documentation? Now, the current version is published to the root of the gh-pages branch. Perhaps we keep that but make a subdirectory for older versions. That would be additional task(s) for the workflow. But maybe there is already automation for this.

prjemian commented 2 years ago

hint: save a build as as an artifact as described

prjemian commented 2 years ago

Note that each build is available as a download artifact: https://github.com/nexusformat/definitions/actions/runs/3098877880

Look at the bottom of the page: Clipboard01

phyy-nx commented 2 years ago

From Dec 2 2022 telco, add 'Preview documentation for next release (v2022.07 + N commits + 7 digit commit hash)' label to documentation (header or footer). Also, proposal is to make the default selection the most recent release, not the state of the main branch.

Originally posted by @phyy-nx in https://github.com/nexusformat/definitions/issues/1228#issuecomment-1335428418

prjemian commented 1 year ago

Here is a working example in a demo repository: https://prjemian.github.io/demo2301/1.0.3/v_swi.html

The NeXus docs may be too bit to keep multiple versions in the gh-pages branch. (Makes clones of the definitions repository very large.) If so, we can explore keeping the cache of versions on a remote server.

prjemian commented 1 year ago