ESCOMP / CISM-wrapper

Community Ice Sheet Model wrapper for CESM
http://www.cesm.ucar.edu/models/cesm2.0/land-ice/
Other
3 stars 16 forks source link

Provide a version drop-down menu in documentation #23

Closed billsacks closed 5 years ago

billsacks commented 5 years ago

This uses a new documentation theme together with some javascript to provide a version drop-down menu in the documentation build.

This is based on what @mnlevy1981 did for MARBL in https://github.com/marbl-ecosys/MARBL/commit/ddd346f138b62c8415a0671f59777897ca956c99 . That, in turn, was based on what's done in https://github.com/unidata/metpy.

Note that the necessary version of sphinx-rtd-theme is only available on a branch right now (in an open PR to that project). Rather than requiring installation of this, I have pulled it in as a subtree:

git subtree add --prefix doc/source/_themes/sphinx_rtd_theme git@github.com:rtfd/sphinx_rtd_theme.git version-dropdown --squash

This relies on having a versions.json file in the documentation build (in path, cism-in-cesm/versions/versions.json). Its current contents are:

{
    "master": "master",
    "release-cesm2.0": "CESM2.0"
}
billsacks commented 5 years ago

I tried pulling sphinx_rtd_theme in via manage_externals, but ran into problems related to the fact that the .gitattributes file in that repository results in a conversion of line endings in docs/make.bat on my Mac - so immediately upon cloning, this file is modified in my working tree, with git giving the message:

warning: CRLF will be replaced by LF in docs/make.bat.
The file will have its original line endings in your working directory.

Then when manage_externals tries to checkout a different hash, it can't:

    error: Your local changes to the following files would be overwritten by checkout:
        docs/make.bat
    Please commit your changes or stash them before you switch branches.

So I'll stick with the subtree for now.