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

WIP: Documentation: provide a version dropdown menu and change theme #3437

Closed
wants to merge 4 commits into from
Closed

WIP: Documentation: provide a version dropdown menu and change theme #3437

wants to merge 4 commits into from

Conversation

billsacks
Copy link
Member

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 I have brought the
necessary theme in as a subtree, because I'm not aware of an
out-of-the-box sphinx theme that provides this support (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.

Note that this implementation is borrowed from
ESCOMP/CISM-wrapper#23, which 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 brought
this theme in as a subtree to simplify the process of building the
documentation (avoiding the need for a separate pip install of the
theme). 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.

Specifically, I added the subtree with the following:

git subtree add --prefix doc/source/_themes/sphinx_rtd_theme [email protected]:rtfd/sphinx_rtd_theme.git version-dropdown --squash

Search functionality was broken in this version of the theme, so I also
cherry-picked a commit to fix search (from
readthedocs/sphinx_rtd_theme#672):

git remote add readthedocs [email protected]:readthedocs/sphinx_rtd_theme.git
git fetch readthedocs
git cherry-pick -X subtree=doc/source/_themes/sphinx_rtd_theme ebbf3d1697c6518a3e398144610b9951bd7ab583

@mvertens and I then made the various other changes that you can see in
doc/source in this PR, which mainly borrowed from
ESCOMP/CISM-wrapper#23.

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:

<!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:

{
    "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:

billsacks and others added 4 commits March 6, 2020 10:13
@billsacks
Squashed 'doc/source/_themes/sphinx_rtd_theme/' content from commit b…
7be0a90 
…46bba516

git-subtree-dir: doc/source/_themes/sphinx_rtd_theme
git-subtree-split: b46bba51649fd15b90e6938b57a1e96f7063c81f
@billsacks
Merge commit '7be0a9069ca00f852649b86b4dac9948ff077207' as 'doc/sourc…
dad2727 
…e/_themes/sphinx_rtd_theme'
@tk0miya @billsacks
Fix HTML search not working with Sphinx-1.8. (ESMCI#672)
0e198be 
* Fix HTML search not working

Since Sphinx-1.7, Sphinx has exported search options as
`documentation_options.js`.  This starts to refer it instead of
definitions of JavaScript variables.
In addition, this also uses `js_tag()` function which added in 1.8
to support additional attributes for scripts (ex. async attribute).

* Add code comment
@billsacks
Allow versioned documentation with a pull-down menu
79f2975 
This changes the documentation theme to use the readthedocs theme, with
some JavaScript that provides capabilities for a dropdown menu allowing
you to select between different versions.

This mimics the changes in
ESCOMP/CISM-wrapper#23
@billsacks billsacks requested review from rljacob and mvertens March 6, 2020 19:07
@billsacks billsacks self-assigned this Mar 6, 2020
@billsacks
Copy link
Member Author

Actually, I don't love that I needed to bring in the sphinx rtd theme as a subtree, and I am now thinking of requiring a separate pip install for this (which I would document on the wiki) - in part because that will facilitate keeping it up-to-date and in sync across our multiple repositories that use this theme. So I will probably close this PR and open a new one that is basically the same except doesn't include the theme inline.

@billsacks billsacks changed the title Documentation: provide a version dropdown menu and change theme WIP: Documentation: provide a version dropdown menu and change theme Mar 6, 2020
@billsacks
Copy link
Member Author

@rljacob - note that we have already pushed the resulting documentation build to http://esmci.github.io/cime - so you can take a look at that to see the end result.

@billsacks
Copy link
Member Author

Closing in favor of #3439

@billsacks billsacks closed this Mar 8, 2020
@billsacks billsacks deleted the versioned_docs2 branch March 16, 2020 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rljacob rljacob Awaiting requested review from rljacob

@mvertens mvertens Awaiting requested review from mvertens

Assignees

@billsacks billsacks

Labels
tp: documentation ty: enhancement
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@billsacks @tk0miya