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

provide docs for any version #4

Closed
prjemian opened this issue Jan 1, 2023 · 19 comments · Fixed by #5
Closed

provide docs for any version #4

prjemian opened this issue Jan 1, 2023 · 19 comments · Fixed by #5
Assignees
@prjemian
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@prjemian
Copy link
Owner

prjemian commented Jan 1, 2023

prototype for BCDA-APS/apstools#713
@prjemian prjemian added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 1, 2023
@prjemian prjemian self-assigned this Jan 1, 2023
@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023

encountered a problem

@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023

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

prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
CI #4 switch to pydata-sphinx-theme
71135eb
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
99c4f0a
@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023

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

prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4 add logo
6bdb0fe
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
CI #4 remove restriction
684e1d7
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
CI #4 rename
e640a24
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4 add switcher file
565be57
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4 precise version info
4d5420e
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4 discard unused import
873fc41
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
83b0e8d
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
9f86ad4
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
1c0afff
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
971dd87
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4 two items in the list
03de50f
prjemian added a commit that referenced this issue Jan 1, 2023
@prjemian
DOC #4
e60760f
@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023

Need a cache of documentation for previous versions.

@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023

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
Copy link
Owner Author

prjemian commented Jan 1, 2023

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

@prjemian
Copy link
Owner Author

prjemian commented Jan 1, 2023 

<!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 added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4 trial publish
39fe849
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4 nojekyll
8cef699
@prjemian
Copy link
Owner Author

prjemian commented Jan 2, 2023

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
Copy link
Owner Author

prjemian commented Jan 2, 2023

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

@prjemian
Copy link
Owner Author

prjemian commented Jan 2, 2023

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
Copy link
Owner Author

prjemian commented Jan 2, 2023 •
edited
Loading

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

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

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

prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4 renames
03f13fc
@prjemian
Copy link
Owner Author

prjemian commented Jan 2, 2023

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
Copy link
Owner Author

prjemian commented Jan 2, 2023

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

prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4 construct new gh-pages branch
373c394
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4 syntax
352fe24
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4
9780933
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
294d1d1
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
GIT #4 ignore local developer files
57874b7
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4
c14f788
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
9ffdbd3
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
36e319b
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
73338a7
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
7550904
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
199aec5
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4 rebuild switcher.json
0dfc276
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
CI #4
df7428b
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
8d9dc2f
@prjemian
Copy link
Owner Author

prjemian commented Jan 2, 2023

Almost ready.

The dropdown is not working yet.

Still a problem.

prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4
897ca56
prjemian added a commit that referenced this issue Jan 2, 2023
@prjemian
DOC #4 swap the dark/light logos
4cc340b
@prjemian
Copy link
Owner Author

prjemian commented Jan 3, 2023

Other relevant pydata-sphinx-theme version switcher implementations:

@prjemian
Copy link
Owner Author

prjemian commented Jan 3, 2023

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

@prjemian
Copy link
Owner Author

prjemian commented Jan 4, 2023

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

@prjemian
Copy link
Owner Author

prjemian commented Jan 4, 2023

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

@prjemian prjemian mentioned this issue Jan 4, 2023
Closed
prjemian added a commit that referenced this issue Jan 6, 2023
@prjemian
ENH #4 from demo2301 project
3be9258
@prjemian prjemian mentioned this issue Jan 6, 2023
Merged
prjemian added a commit that referenced this issue Jan 6, 2023
@prjemian
MNT #4
4d24d5b
prjemian added a commit that referenced this issue Jan 6, 2023
@prjemian
DOC #4
4bbbcf7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@prjemian prjemian

Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

version switcher dropdown prjemian/pysumreg
1 participant
@prjemian