Add a version selector dropdown to the main menu #438
Conversation
This adds a version selection dropdown to the menu. It is used to redirect on change to the version URL. The ``versions`` theme option is added and is used to add a mapping of version slugs to URLs. Currently, this is going to be used in pydoc.io. The implementation will change the javascript slightly, to accept json data instead of a blob of HTML. This will currently be disabled on Read the Docs, as we are rethinking what the version selection menu looks like.
agjohnson
added
the
PR: work in progress
agjohnson
requested review from
Blendify and
ericholscher
and removed request for
Blendify
|
For simplicity can we get rid of the unrelated changes? Opening these as separate PRs if necessary. All in all, I can see this being helpful rather than leaving it up to users to write there own. But maybe instead of putting it in the |
|
@Blendify can you clarify the |
|
Oh, I see -- it's in that block in the sidebar. +1 on adding it outside of the search div. |
|
This isn't a problem of the version selector being placed in the wrong element, but the element was poorly named initially. |
|
For myself, I prefer it down there. This is where we wrote our custom version switch for my other project. |
The feature itself is fine and we should merge this. Although I think after we merge this we need to make a final decision on how this will work on readthedocs and where in the html template it should go. We should also add support for a language drop down. Also it seems you ran grunt before committing to the branch so those changes need to be reverted before merging. |
|
Yes please 👍 |
|
Ok, so they are getting back from a month or so of vacation but after other important task get done we can have a look at this. |
|
Just dropped these changes into some docs that I'm building locally, and I'm running into a few issues. They are likely due to me not configuring my project correctly, but I'm not really sure how this is supposed to work after reading this thread and the changes to the docs. For reference, I am used to using Sphinx-Versioning (https://robpol86.github.io/sphinxcontrib-versioning/index.html) to achieve this same goal. In Sphinx-Versioning, each version is a completely separate project, with separate conf.py files and such. Is the intent to do the same with this feature, where each project has the same versions dictionary and then routes to the other's url? That seems to be a proper way of handling it, with the exception of building docs locally. If there was any way to specify relative links instead of urls for the versions that would make it much easier to test. Additionally, the dropdown box looks much different and generic compared to the example in the original post here. Granted, I have modified a decent bit of the theme's color scheme so that's a very likely source of the disparity, but I have not touched any other parameters or characteristics of the theme besides the colors. Any ideas as to what could cause the differences, or is it more than likely due to my own meddling? A picture for reference: |
|
I'd like to rethink how this could be used for RTD. We have some thoughts on what a new menu is going to be like, but i do like having an additional pattern like this for switching versions on RTD. Eventually, the menu is going to at least be API driven and not just a blob of HTML handed out by RTD. |
|
I'm curious if there are any plans for this or similar functionality to be merged to the master version of this theme. I'm maintaining a few projects where we are hosting our documentation on github.io (rather than readthedocs), but want versioning functionality. We are currently using this branch to do so, and I'm wondering if that is what we'll need to do long-term, or if there is some hope that we'll be able to use master for this functionality at some point. |
Documentation: provide a version dropdown menu and change theme The documentation of cime is starting to diverge on the various important branches (master, maint-5.6, and ufs_release_v1.0). This PR, along with similar PRs for maint-5.6 and ufs_release_v1.0, and some changes to the gh-pages branch, support having versioned documentation, with a dropdown menu. This also changes the documentation theme to a theme that supports this version dropdown. Note that this requires a branch of the sphinx_rtd_theme; I will update the cime wiki on building the documentation to note the new pip install step needed for that. (See below for more details.) At a high level, the way the versioned documentation works is to have separate subdirectories in the gh-pages branch for each version of the documentation we want to support. There is then a bit of JavaScript code which uses a json file in the gh-pages branch to determine which versions exist and how these should be named in the dropdown menu. This changes the documentation build process slightly; I will update the wiki to reflect these changes. @mvertens and I made the various changes that you can see in `doc/source` in this PR, which mainly borrowed from ESCOMP/CISM-wrapper#23. That, in turn, is a slight modification of an implementation provided by @MNLevy for the MARBL documentation, which in turn borrowed from an implementation put together by Unidata (credit where credit is due). As mentioned above, I am not aware of out-of-the-box support for a version pull-down in out-of-the-box sphinx themes (though the last time I looked was in Fall, 2018, so there may be something available now). However, support for a version dropdown exists in an open PR in the sphinx readthedocs theme repository: readthedocs/sphinx_rtd_theme#438. I have pushed this branch to a new repository in ESMCI (https://github.com/ESMCI/sphinx_rtd_theme) to facilitate long-term maintenance of this branch in case it disappears from the official sphinx_rtd_theme repository. I have also cherry-picked a commit onto that branch, which is needed to fix search functionality in sphinx1.8 (from readthedocs/sphinx_rtd_theme#672) (which is another reason for maintaining our own copy of this branch). The branch in this repository is now named version-dropdown-with-fixes (branching off of the version-dropdown branch in the sphinx_rtd_theme repository). I will update the wiki to give the additional pip install command needed to install this repository before doing the build. In the long-term, I am a little concerned about using this theme that isn't showing any signs of being merged to the main branch of the readthedocs theme, but this has been working for us in other projects for the last 2 years, so I feel this is a reasonable approach in the short-medium term. A few changes were also needed in the gh-pages branch: - A `versions` directory was introduced at the top level, with subdirectories for each documentation version we want to support. We are using the convention that these subdirectories should have names that match the corresponding cime branches, to avoid uncertainty. - A top-level index.html page was introduced that redirects to the master version of the documentation: ```html <!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="refresh" content="0; url=versions/master/html/index.html" /> </head> </html> ``` - Other than those files and an empty `.nojekyll` file, everything else was removed from the top level directory of the documentation. - In the versions directory, we also introduced a `versions.json` file. This lists the versions and provides a mapping between directory names and the names used in the pull-down menu: ```json { "master": "master", "maint-5.6": "cime5.6", "ufs_release_v1.0": "ufs_release_v1.0" } ``` - The complete contents of each version subdirectory are generated by the documentation build script. Thus, it is safe to remove the contents of (e.g.) `versions/master/` before rebuilding the documentation for that version. The documentation build is done similarly to before, but now providing a BUILDDIR argument to the make command in order to build in the correct subdirectory. For example, when building the documentation for master, you would provide `BUILDDIR=/path/to/cime_gh_pages_repo/versions/master/`. Test suite: none Test baseline: n/a Test namelist changes: none Test status: bit for bit Fixes none User interface changes?: none Update gh-pages html (Y/N)?: Y (already done) Code review:
Bring documentation source to master 1. Bring documentation source to master: Pulls in the source from https://github.com/escomp/ctsm-docs. This is important so that documentation can remain in sync with changes in the model code. Images are stored here using git-lfs (Git Large File Storage). I also made some minor fixes to get the pdf build of the tech note working. 2. Use a different documentation theme that supports a version dropdown menu, and add the code needed to support this versioning on the documentation web pages. At a high level, the way the versioned documentation works is to have separate subdirectories in the gh-pages branch of the ctsm-docs repository for each version of the documentation we want to support. There is then a bit of JavaScript code which uses a json file in the gh-pages branch to determine which versions exist and how these should be named in the dropdown menu. Most of these changes were borrowed from ESMCI/cime#3439, which in turn borrowed from ESCOMP/CISM-wrapper#23, which in turn was a slight modification of an implementation provided by @mnlevy1981 for the MARBL documentation, which in turn borrowed from an implementation put together by Unidata (credit where credit is due). I am not aware of out-of-the-box support for a version pull-down in out-of-the-box sphinx themes (though the last time I looked was in Fall, 2018, so there may be something available now). However, support for a version dropdown exists in an open PR in the sphinx readthedocs theme repository: readthedocs/sphinx_rtd_theme#438. I have pushed this branch to a new repository in ESMCI (https://github.com/ESMCI/sphinx_rtd_theme) to facilitate long-term maintenance of this branch in case it disappears from the official sphinx_rtd_theme repository. I have also cherry-picked a commit onto that branch, which is needed to fix search functionality in sphinx1.8 (from readthedocs/sphinx_rtd_theme#672) (which is another reason for maintaining our own copy of this branch). The branch in this repository is now named version-dropdown-with-fixes (branching off of the version-dropdown branch in the sphinx_rtd_theme repository). In the long-term, I am a little concerned about using this theme that isn't showing any signs of being merged to the main branch of the readthedocs theme, but this has been working for us in other projects for the last 2 years, so I feel this is a reasonable approach in the short-medium term. The new process for building the documentation is given here: https://github.com/ESCOMP/CTSM/wiki/Directions-for-editing-CLM-documentation-on-github-and-sphinx Resolves #239
Bring documentation source to master 1. Bring documentation source to master: Pulls in the source from https://github.com/escomp/ctsm-docs. This is important so that documentation can remain in sync with changes in the model code. Images are stored here using git-lfs (Git Large File Storage). I also made some minor fixes to get the pdf build of the tech note working. 2. Use a different documentation theme that supports a version dropdown menu, and add the code needed to support this versioning on the documentation web pages. At a high level, the way the versioned documentation works is to have separate subdirectories in the gh-pages branch of the ctsm-docs repository for each version of the documentation we want to support. There is then a bit of JavaScript code which uses a json file in the gh-pages branch to determine which versions exist and how these should be named in the dropdown menu. Most of these changes were borrowed from ESMCI/cime#3439, which in turn borrowed from ESCOMP/CISM-wrapper#23, which in turn was a slight modification of an implementation provided by @mnlevy1981 for the MARBL documentation, which in turn borrowed from an implementation put together by Unidata (credit where credit is due). I am not aware of out-of-the-box support for a version pull-down in out-of-the-box sphinx themes (though the last time I looked was in Fall, 2018, so there may be something available now). However, support for a version dropdown exists in an open PR in the sphinx readthedocs theme repository: readthedocs/sphinx_rtd_theme#438. I have pushed this branch to a new repository in ESMCI (https://github.com/ESMCI/sphinx_rtd_theme) to facilitate long-term maintenance of this branch in case it disappears from the official sphinx_rtd_theme repository. I have also cherry-picked a commit onto that branch, which is needed to fix search functionality in sphinx1.8 (from readthedocs/sphinx_rtd_theme#672) (which is another reason for maintaining our own copy of this branch). The branch in this repository is now named version-dropdown-with-fixes (branching off of the version-dropdown branch in the sphinx_rtd_theme repository). In the long-term, I am a little concerned about using this theme that isn't showing any signs of being merged to the main branch of the readthedocs theme, but this has been working for us in other projects for the last 2 years, so I feel this is a reasonable approach in the short-medium term. The new process for building the documentation is given here: https://github.com/ESCOMP/CTSM/wiki/Directions-for-editing-CLM-documentation-on-github-and-sphinx Resolves ESCOMP#239
Bring documentation source to master 1. Bring documentation source to master: Pulls in the source from https://github.com/escomp/ctsm-docs. This is important so that documentation can remain in sync with changes in the model code. Images are stored here using git-lfs (Git Large File Storage). I also made some minor fixes to get the pdf build of the tech note working. 2. Use a different documentation theme that supports a version dropdown menu, and add the code needed to support this versioning on the documentation web pages. At a high level, the way the versioned documentation works is to have separate subdirectories in the gh-pages branch of the ctsm-docs repository for each version of the documentation we want to support. There is then a bit of JavaScript code which uses a json file in the gh-pages branch to determine which versions exist and how these should be named in the dropdown menu. Most of these changes were borrowed from ESMCI/cime#3439, which in turn borrowed from ESCOMP/CISM-wrapper#23, which in turn was a slight modification of an implementation provided by @mnlevy1981 for the MARBL documentation, which in turn borrowed from an implementation put together by Unidata (credit where credit is due). I am not aware of out-of-the-box support for a version pull-down in out-of-the-box sphinx themes (though the last time I looked was in Fall, 2018, so there may be something available now). However, support for a version dropdown exists in an open PR in the sphinx readthedocs theme repository: readthedocs/sphinx_rtd_theme#438. I have pushed this branch to a new repository in ESMCI (https://github.com/ESMCI/sphinx_rtd_theme) to facilitate long-term maintenance of this branch in case it disappears from the official sphinx_rtd_theme repository. I have also cherry-picked a commit onto that branch, which is needed to fix search functionality in sphinx1.8 (from readthedocs/sphinx_rtd_theme#672) (which is another reason for maintaining our own copy of this branch). The branch in this repository is now named version-dropdown-with-fixes (branching off of the version-dropdown branch in the sphinx_rtd_theme repository). In the long-term, I am a little concerned about using this theme that isn't showing any signs of being merged to the main branch of the readthedocs theme, but this has been working for us in other projects for the last 2 years, so I feel this is a reasonable approach in the short-medium term. The new process for building the documentation is given here: https://github.com/ESCOMP/CTSM/wiki/Directions-for-editing-CLM-documentation-on-github-and-sphinx Resolves ESCOMP#239
Bring documentation source to master 1. Bring documentation source to master: Pulls in the source from https://github.com/escomp/ctsm-docs. This is important so that documentation can remain in sync with changes in the model code. Images are stored here using git-lfs (Git Large File Storage). I also made some minor fixes to get the pdf build of the tech note working. 2. Use a different documentation theme that supports a version dropdown menu, and add the code needed to support this versioning on the documentation web pages. At a high level, the way the versioned documentation works is to have separate subdirectories in the gh-pages branch of the ctsm-docs repository for each version of the documentation we want to support. There is then a bit of JavaScript code which uses a json file in the gh-pages branch to determine which versions exist and how these should be named in the dropdown menu. Most of these changes were borrowed from ESMCI/cime#3439, which in turn borrowed from ESCOMP/CISM-wrapper#23, which in turn was a slight modification of an implementation provided by @mnlevy1981 for the MARBL documentation, which in turn borrowed from an implementation put together by Unidata (credit where credit is due). I am not aware of out-of-the-box support for a version pull-down in out-of-the-box sphinx themes (though the last time I looked was in Fall, 2018, so there may be something available now). However, support for a version dropdown exists in an open PR in the sphinx readthedocs theme repository: readthedocs/sphinx_rtd_theme#438. I have pushed this branch to a new repository in ESMCI (https://github.com/ESMCI/sphinx_rtd_theme) to facilitate long-term maintenance of this branch in case it disappears from the official sphinx_rtd_theme repository. I have also cherry-picked a commit onto that branch, which is needed to fix search functionality in sphinx1.8 (from readthedocs/sphinx_rtd_theme#672) (which is another reason for maintaining our own copy of this branch). The branch in this repository is now named version-dropdown-with-fixes (branching off of the version-dropdown branch in the sphinx_rtd_theme repository). In the long-term, I am a little concerned about using this theme that isn't showing any signs of being merged to the main branch of the readthedocs theme, but this has been working for us in other projects for the last 2 years, so I feel this is a reasonable approach in the short-medium term. The new process for building the documentation is given here: https://github.com/ESCOMP/CTSM/wiki/Directions-for-editing-CLM-documentation-on-github-and-sphinx Resolves ESCOMP#239
|
No, I don't think this feature will be merged as-is. The problem with this approach so far is that this is a build-time only feature, meaning as soon as the version list is updated, this menu is inaccurate. We don't want to continue adding features like this, however our API is not where it needs to be to support a feature like this. I'm going to close this for now. |
|
@agjohnson thanks for your reply - and thank you for all of your work on this project. FYI, and in case it happens to be useful to you: We use this version of the theme with a bit of added JavaScript code that sets the versions dynamically. To add a version, the only thing needed is to add a line to a json file in the build directory – no rebuild is needed. For details of what we do, see ESMCI/cime#3439 - both the files changed and the initial comment in the PR. (The json file I'm referring to looks like this: https://github.com/ESMCI/cime/blob/f8dba01bbdfbf0c86e132be08490ae001815c64d/versions/versions.json .) (I'll be honest, though: I am far from an expert in web development and don't totally understand how this works: I inherited it from others.) I'll also note, in case it's useful to others, that we're maintaining this branch in a fork (https://github.com/ESMCI/sphinx_rtd_theme/tree/version-dropdown-with-fixes), so that we can cherry-pick any critical bug fixes into this branch (currently just ESMCI@05a46f5). |
This adds a version selection dropdown to the menu. It is used to redirect on
change to the version URL. The
versionstheme option is added and is used toadd a mapping of version slugs to URLs.
Currently, this is going to be used in pydoc.io. The implementation will change
the javascript slightly, to accept json data instead of a blob of HTML.
This will currently be disabled on Read the Docs, as we are rethinking what the
version selection menu looks like.