Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request ESMCI#3439 from billsacks/versioned_docs3
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:
- Loading branch information
