provide docs for any version

prjemian / pysumreg

Statistics of list of (x, y) pairs from calculator-style summation registers.

https://prjemian.github.io/pysumreg/

0 stars 0 forks source link

provide docs for any version #4

Closed prjemian closed 1 year ago

prjemian commented 1 year ago

prototype for https://github.com/BCDA-APS/apstools/issues/713

prjemian commented 1 year ago

encountered a problem

prjemian commented 1 year ago

The problem is conflict between pydata-sphinx-theme and new Sphinx 6.0 release. Restrict sphinx<6 (for now).

prjemian commented 1 year ago

Added light & dark logos and remove restriction to avoid the problem reported above.

prjemian commented 1 year ago

Need a cache of documentation for previous versions.

prjemian commented 1 year ago

Looking at a structure such as:

BASE_URL
    ./ --> redirects to 1.0.4
    dev
    1.0.4 <-- latest
    1.0.3
    1.0.1
    1.0.0

Older versions may not have the dropdown to switch versions. (Because they do not use that theme, or some other reason(s).)

prjemian commented 1 year ago

https://www.w3docs.com/snippets/html/how-to-redirect-a-web-page-in-html.html

prjemian commented 1 year ago

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="refresh" content="15; url='https://prjemian.github.io/pysumreg/'" />
  </head>
  <body>
    <p>
        Click <a href="https://prjemian.github.io/pysumreg/1.0.4/">here</a>
        or wait 15 seconds to redirect automatically to documentation of
        the latest release.
    </p>
  </body>
</html>

prjemian commented 1 year ago

Manually created the structure on gh-pages branch and pushed. The dropdown is not working yet. Also the _static/switcher.json file must be moved.

prjemian commented 1 year ago

Ran existing actions workflow to re-publish the standard way (clears the temporary structure).

prjemian commented 1 year ago

After building the html docs for a release, create a .tar.gz file and add it to the release assets. Such as pysumreg-docs-1.0.0.tar.gz for release 1.0.0.

prjemian commented 1 year ago

Need a script/something to use in the pages workflow:

[x] make a temporary directory (mktemp)
[x] build the sphinx docs into it (sphinx-build -M html ./docs/source /tmp/tmp.XXXXXX)
[x] copy the built html to a dev subdirectory (mv /tmp/tmp.XXXXXX/build/html /tmp/tmp.XXXXXX/dev)
[x] download and untar all the old versions of documentation
[x] rebuild the switcher.json file accordingly
[x] soft link dev to the appropriate version
[x] soft link latest to the appropriate version

Then use the GHA action to post this directory to gh-pages.

prjemian commented 1 year ago

Limit the number of old documentation versions to 5-10.

prjemian commented 1 year ago

Instead of rebuilding (or downloading an unzipping) all old documentation versions, consider downloading the existing gh-pages branch and rebuilding on top of that.

prjemian commented 1 year ago

wget https://github.com/prjemian/pysumreg/archive/refs/heads/gh-pages.zip

prjemian commented 1 year ago

Almost ready.

The dropdown is not working yet.

Still a problem.

prjemian commented 1 year ago

Other relevant pydata-sphinx-theme version switcher implementations:

prjemian commented 1 year ago

Review this trail of PRs: https://github.com/numpy/numpy/pulls?q=is%3Apr+switcher+is%3Aclosed

prjemian commented 1 year ago

For a simplified example, watch this project: https://github.com/prjemian/demo2301

prjemian commented 1 year ago

demo2301 is ready, see https://prjemian.github.io/demo2301/1.0.0/index.html