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

Documentation: provide a version dropdown menu and change theme #3439

Merged
merged 4 commits into from
Mar 14, 2020
Merged

Documentation: provide a version dropdown menu and change theme #3439

merged 4 commits into from
Mar 14, 2020

Conversation

billsacks
Copy link
Member

@billsacks billsacks commented Mar 8, 2020 •
edited
Loading

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 @mnlevy1981 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:

<!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
Allow versioned documentation with a pull-down menu
d95f3e7 
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

The changes in this commit assume that sphinx_rtd_theme is installed in
_themes. However, we are not going to do this here: instead, we'll rely
on a pip install of an appropriate branch of sphinx_rtd_theme, using:

pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes

A follow-up commit will fix that.
@billsacks
Changes to use sphinx_rtd_theme from pip install rather than in _themes
0307839 
I don't like having this theme as a subtree for two reasons:
- Bloats the cime repo
- If we do this in all projects that need it, that's a maintenance issue
  if we need to update it. It would be better if we could just make
  updates to the themes in one place.

This assumes that we have done a pip install of the correct branch:

pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes
@billsacks
Remove sphinx_rtd_theme from list of extensions
50bdb88 
When it was in the list of extensions, I got this warning when building
documentation:

WARNING: extension 'sphinx_rtd_theme' has no setup() function; is it really a Sphinx extension module?

I'm thinking that we're using an older version of sphinx_rtd_theme that
doesn't support this. From the documentation, I see:

   Adding this theme as an extension is what enables localization of
   theme strings in your translated output. If these strings are not
   translated in your output, either we lack the localized strings for
   your locale, or you are using an old version of the theme.
@billsacks billsacks self-assigned this Mar 8, 2020
@billsacks billsacks mentioned this pull request Mar 8, 2020
Closed
@billsacks
Copy link
Member Author

@rljacob - as I mentioned in the earlier PR, 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.

Once this is approved, I will open similar PRs to the maint-5.6 and ufs_release_v1.0 branches.

@billsacks
Update doc README
758a5b8 
Add pip install commands, remove some pieces that are no longer correct.
@rljacob
Copy link
Member

rljacob commented Mar 11, 2020

I suppose this was inevitable but was hoping we could put it off a bit longer. There are still some holes in the documentation which now would need to be replicated in 3 places when filled?

@billsacks
Copy link
Member Author

I suppose this was inevitable but was hoping we could put it off a bit longer. There are still some holes in the documentation which now would need to be replicated in 3 places when filled?

Yes, that's certainly a downside. My understanding from @mvertens, though, is that this is truly needed at this point because documentation is starting to diverge between the different branches.

@mvertens I'll merge once you give your formal approval.

@rsdunlapiv
Copy link
Collaborator

I did not think that this was about diverging documentation, but instead the need for a tag to lock down this point in time. In my view the CIME docs should not diverge, but contain information about all common parts of CIME, regardless of the modeling system. If there are diverging aspects, then in draws into question whether a separate modeling-system specific documentation layer is needed. However, in this specific case, I don't think it is about diverging docs. In fact, didn't we tag the docs "as is" ("as are?") without adding anything specific about UFS?

@mvertens
Copy link
Contributor

@rsdunlapiv - you really do need to have 3 branches for the cime documentation right now. There are changes in the data models that only relate to the latest developments and are not in the cesm release. The same is true for other updates to CIME. As for the UFS release, there could be other additions that do not relate to cesm or e3sm. I'm not sure that the documentation is divergent just that there is a separation of concerns that having the 3 branches permits us to address.

@rsdunlapiv
Copy link
Collaborator

Will all the branches be merged back together, e.g., when the updated data models are available in CESM? Just trying to understand if this branching is needed due to fundamental differences between the modeling systems, or if it used to manage the fact that different modeling systems are using different versions of CIME.

@rljacob
Copy link
Member

rljacob commented Mar 11, 2020

I'm now wondering this too. If the UFS data models are going to live on master, they should be documented on master. Is the UFS branch going to live forever and diverge? Why would UFS not want to track master?

@mvertens
Copy link
Contributor

mvertens commented Mar 11, 2020 via email

@jedwards4b
Copy link
Contributor

I am working on a PR now to merge the ufs branch back to master and the next ufs release should be a new branchpoint from master, but the ufs developers wanted a documentation branch that was fixed with respect to the release version.

@rljacob
Copy link
Member

rljacob commented Mar 11, 2020

Any specific version UFS wants to use should be tagged (on master) and we should find a way to build docs for specific tags. If the docs or other things need to be fixed, a maintenance branch would be made off that tag and the docs for that version built from the head of that branch.

Everything in master should be documented on master.

@jedwards4b
Copy link
Contributor

@rljacob I think that's what this does, the ufs_v1.0.0 documentation is on a branch and future ufs development will occur on master, with only bug fixes going on the ufs_release_v1.0 branch.

@jedwards4b
Copy link
Contributor

@rljacob I should say the documentation is tied to the tag ufs_v1.0.0 which is on a branch.

@rljacob
Copy link
Member

rljacob commented Mar 11, 2020

Ok. That branch point should have a cimeX.Y.X tag as well. Anytime UFS wants a release, there should be a corresponding cime tag.

@billsacks billsacks merged commit 4f18807 into ESMCI:master Mar 14, 2020
@billsacks billsacks deleted the versioned_docs3 branch March 14, 2020 21:39
This was referenced Mar 16, 2020
Merged
Merged
ekluzek added a commit to ekluzek/cime that referenced this pull request Mar 20, 2020
@ekluzek
Merge tag 'cime5.8.17' into mizuRoute
405e23e 
Tagging cime5.8.17

Originator: Bill Sacks
Date: 3-15-2020
Tag: cime5.8.17
Answer Changes: None
Tests: scripts_regression_tests, aux_clm
Dependencies: none

Brief Summary:
    - Separate mct and nuopc data, xcpl and stub components
    - Update pio2
    - Documentation: provide a version dropdown menu and change theme
    - Add ne5pg2_ne5pg2_mg37 grid
    - Fix some issues

User interface changes: None

PR summary: git log --oneline --first-parent [previous_tag]..master
4f18807 Merge pull request ESMCI#3439 from billsacks/versioned_docs3
38c2b9f Merge pull request ESMCI#3441 from jedwards4b/thunder_port
5d9ff80 Merge pull request ESMCI#3451 from jedwards4b/check_inputdata_fix
3444503 Merge pull request ESMCI#3449 from ESMCI/jgfouca/improve_case_setup_clean
02a8eeb fix default for PIO_REARRANGER
49e82c6 Merge pull request ESMCI#3447 from jedwards4b/pio2_update
ada1f09 Merge pull request ESMCI#3445 from ESMCI/fischer/ne5pg2
bbba1af Merge pull request ESMCI#3444 from alperaltuntas/datm_mesh_tol
acc2d23 Merge commit 'e5265f03a6a8e1806e1b463b00c006b365e149d4'
fadc3ee resolve conflicts
614b311 Merge pull request ESMCI#3440 from ESMCI/fischer/aq_scam
328e387 Merge pull request ESMCI#3392 from ESMCI/mvertens/new_component_directories3
a93ced5 need to explicitly state compiler used
bf09ad8 minor change to get FFLAGS
20856d8 Merge pull request ESMCI#3431 from jedwards4b/complete_cprnc_fix
7fd3dae Merge pull request ESMCI#3430 from ESMCI/jgfouca/sharedlib_bld_serialization
e75142f Merge pull request ESMCI#3424 from ESMCI/cprnc_build_machine

Modified files: git diff --name-status [previous_tag]
M	config/cesm/config_files.xml
M	config/cesm/config_grids.xml
M	config/cesm/machines/config_batch.xml
M	config/cesm/machines/config_compilers.xml
M	config/cesm/machines/config_machines.xml
M	config/cesm/machines/config_pio.xml
M	config/e3sm/config_files.xml
M	config/ufs/config_files.xml
M	config/ufs/config_inputdata.xml
M	config/ufs/machines/config_batch.xml
M	config/ufs/machines/config_compilers.xml
M	config/ufs/machines/config_machines.xml
M	config/ufs/machines/config_workflow.xml
M	config/ufs/machines/template.chgres.run
M	config/ufs/machines/template.gfs_post.run
M	doc/README
D	doc/source/_static
A	doc/source/_static/pop_ver.js
A	doc/source/_templates/footer.html
A	doc/source/_templates/layout.html
M	doc/source/conf.py
M	scripts/lib/CIME/SystemTests/pre.py
M	scripts/lib/CIME/XML/env_batch.py
M	scripts/lib/CIME/build.py
M	scripts/lib/CIME/buildlib.py
M	scripts/lib/CIME/case/case_setup.py
M	scripts/lib/CIME/case/check_input_data.py
M	scripts/lib/CIME/case/preview_namelists.py
M	scripts/lib/CIME/hist_utils.py
M	scripts/lib/CIME/test_scheduler.py
M	scripts/tests/CMakeLists.txt
M	scripts/tests/scripts_regression_tests.py
M	src/build_scripts/buildlib.cprnc
D	src/components/data_comps/datm/doc/bookinfo.xml
D	src/components/data_comps/datm/doc/datacomps.xml
D	src/components/data_comps/datm/doc/intro.xml
D	src/components/data_comps/datm/doc/rundocbook.csh
D	src/components/data_comps/datm/doc/streams.xml
D	src/components/data_comps/datm/doc/ug.xml
D	src/components/data_comps/docn/tools/pop_som_frc/SOM.pdf
D	src/components/data_comps/dwav/bld/README
R100	src/components/data_comps/datm/cime_config/buildlib	src/components/data_comps_mct/datm/cime_config/buildlib
R100	src/components/data_comps/datm/cime_config/buildnml	src/components/data_comps_mct/datm/cime_config/buildnml
R100	src/components/data_comps/datm/cime_config/config_archive.xml	src/components/data_comps_mct/datm/cime_config/config_archive.xml
R100	src/components/data_comps/datm/cime_config/config_component.xml	src/components/data_comps_mct/datm/cime_config/config_component.xml
R100	src/components/data_comps/datm/cime_config/namelist_definition_datm.xml	src/components/data_comps_mct/datm/cime_config/namelist_definition_datm.xml
R100	src/components/data_comps/datm/cime_config/user_nl_datm	src/components/data_comps_mct/datm/cime_config/user_nl_datm
R100	src/components/data_comps/datm/mct/atm_comp_mct.F90	src/components/data_comps_mct/datm/src/atm_comp_mct.F90
R100	src/components/data_comps/datm/mct/datm_comp_mod.F90	src/components/data_comps_mct/datm/src/datm_comp_mod.F90
R100	src/components/data_comps/datm/mct/datm_shr_mod.F90	src/components/data_comps_mct/datm/src/datm_shr_mod.F90
R100	src/components/data_comps/desp/cime_config/buildlib	src/components/data_comps_mct/desp/cime_config/buildlib
R099	src/components/data_comps/desp/cime_config/buildnml	src/components/data_comps_mct/desp/cime_config/buildnml
R100	src/components/data_comps/desp/cime_config/config_component.xml	src/components/data_comps_mct/desp/cime_config/config_component.xml
R100	src/components/data_comps/desp/cime_config/namelist_definition_desp.xml	src/components/data_comps_mct/desp/cime_config/namelist_definition_desp.xml
R100	src/components/data_comps/desp/cime_config/user_nl_desp	src/components/data_comps_mct/desp/cime_config/user_nl_desp
R100	src/components/data_comps/desp/desp_comp_mod.F90	src/components/data_comps_mct/desp/desp_comp_mod.F90
R100	src/components/data_comps/desp/esp_utils.F90	src/components/data_comps_mct/desp/esp_utils.F90
R100	src/components/data_comps/desp/mct/esp_comp_mct.F90	src/components/data_comps_mct/desp/src/esp_comp_mct.F90
R100	src/components/data_comps/dice/cime_config/buildlib	src/components/data_comps_mct/dice/cime_config/buildlib
R100	src/components/data_comps/dice/cime_config/buildnml	src/components/data_comps_mct/dice/cime_config/buildnml
R100	src/components/data_comps/dice/cime_config/config_archive.xml	src/components/data_comps_mct/dice/cime_config/config_archive.xml
R100	src/components/data_comps/dice/cime_config/config_component.xml	src/components/data_comps_mct/dice/cime_config/config_component.xml
R100	src/components/data_comps/dice/cime_config/namelist_definition_dice.xml	src/components/data_comps_mct/dice/cime_config/namelist_definition_dice.xml
R100	src/components/data_comps/dice/cime_config/user_nl_dice	src/components/data_comps_mct/dice/cime_config/user_nl_dice
R100	src/components/data_comps/dice/mct/dice_comp_mod.F90	src/components/data_comps_mct/dice/src/dice_comp_mod.F90
R100	src/components/data_comps/dice/mct/dice_flux_atmice_mod.F90	src/components/data_comps_mct/dice/src/dice_flux_atmice_mod.F90
R100	src/components/data_comps/dice/mct/dice_shr_mod.F90	src/components/data_comps_mct/dice/src/dice_shr_mod.F90
R100	src/components/data_comps/dice/mct/ice_comp_mct.F90	src/components/data_comps_mct/dice/src/ice_comp_mct.F90
R100	src/components/data_comps/dlnd/cime_config/buildlib	src/components/data_comps_mct/dlnd/cime_config/buildlib
R100	src/components/data_comps/dlnd/cime_config/buildnml	src/components/data_comps_mct/dlnd/cime_config/buildnml
R100	src/components/data_comps/dlnd/cime_config/config_archive.xml	src/components/data_comps_mct/dlnd/cime_config/config_archive.xml
R100	src/components/data_comps/dlnd/cime_config/config_component.xml	src/components/data_comps_mct/dlnd/cime_config/config_component.xml
R100	src/components/data_comps/dlnd/cime_config/namelist_definition_dlnd.xml	src/components/data_comps_mct/dlnd/cime_config/namelist_definition_dlnd.xml
R100	src/components/data_comps/dlnd/cime_config/user_nl_dlnd	src/components/data_comps_mct/dlnd/cime_config/user_nl_dlnd
R100	src/components/data_comps/dlnd/mct/dlnd_comp_mod.F90	src/components/data_comps_mct/dlnd/src/dlnd_comp_mod.F90
R100	src/components/data_comps/dlnd/mct/dlnd_shr_mod.F90	src/components/data_comps_mct/dlnd/src/dlnd_shr_mod.F90
R100	src/components/data_comps/dlnd/mct/lnd_comp_mct.F90	src/components/data_comps_mct/dlnd/src/lnd_comp_mct.F90
R100	src/components/data_comps/docn/cime_config/buildlib	src/components/data_comps_mct/docn/cime_config/buildlib
R100	src/components/data_comps/docn/cime_config/buildnml	src/components/data_comps_mct/docn/cime_config/buildnml
R100	src/components/data_comps/docn/cime_config/config_archive.xml	src/components/data_comps_mct/docn/cime_config/config_archive.xml
R100	src/components/data_comps/docn/cime_config/config_component.xml	src/components/data_comps_mct/docn/cime_config/config_component.xml
R100	src/components/data_comps/docn/cime_config/namelist_definition_docn.xml	src/components/data_comps_mct/docn/cime_config/namelist_definition_docn.xml
R100	src/components/data_comps/docn/cime_config/user_nl_docn	src/components/data_comps_mct/docn/cime_config/user_nl_docn
R099	src/components/data_comps/docn/mct/docn_comp_mod.F90	src/components/data_comps_mct/docn/src/docn_comp_mod.F90
R100	src/components/data_comps/docn/mct/docn_shr_mod.F90	src/components/data_comps_mct/docn/src/docn_shr_mod.F90
R100	src/components/data_comps/docn/mct/ocn_comp_mct.F90	src/components/data_comps_mct/docn/src/ocn_comp_mct.F90
R100	src/components/data_comps/docn/tools/pop_som_frc/README	src/components/data_comps_mct/docn/tools/pop_som_frc/README
R100	src/components/data_comps/docn/tools/pop_som_frc/SOM.doc	src/components/data_comps_mct/docn/tools/pop_som_frc/SOM.doc
R100	src/components/data_comps/datm/doc/SOM.pdf	src/components/data_comps_mct/docn/tools/pop_som_frc/SOM.pdf
R100	src/components/data_comps/docn/tools/pop_som_frc/pop_frc.csh	src/components/data_comps_mct/docn/tools/pop_som_frc/pop_frc.csh
R100	src/components/data_comps/docn/tools/pop_som_frc/pop_frc_mlann.ncl	src/components/data_comps_mct/docn/tools/pop_som_frc/pop_frc_mlann.ncl
R100	src/components/data_comps/docn/tools/pop_som_frc/pop_frc_mlt.ncl	src/components/data_comps_mct/docn/tools/pop_som_frc/pop_frc_mlt.ncl
R100	src/components/data_comps/docn/tools/pop_som_frc/pop_interp.ncl	src/components/data_comps_mct/docn/tools/pop_som_frc/pop_interp.ncl
R100	src/components/data_comps/docn/tools/pop_som_frc/read_from_mss.csh	src/components/data_comps_mct/docn/tools/pop_som_frc/read_from_mss.csh
R100	src/components/data_comps/docn/tools/pop_som_frc/read_from_mss_month.csh	src/components/data_comps_mct/docn/tools/pop_som_frc/read_from_mss_month.csh
R100	src/components/data_comps/drof/cime_config/buildlib	src/components/data_comps_mct/drof/cime_config/buildlib
R100	src/components/data_comps/drof/cime_config/buildnml	src/components/data_comps_mct/drof/cime_config/buildnml
R100	src/components/data_comps/drof/cime_config/config_archive.xml	src/components/data_comps_mct/drof/cime_config/config_archive.xml
R100	src/components/data_comps/drof/cime_config/config_component.xml	src/components/data_comps_mct/drof/cime_config/config_component.xml
R100	src/components/data_comps/drof/cime_config/namelist_definition_drof.xml	src/components/data_comps_mct/drof/cime_config/namelist_definition_drof.xml
R100	src/components/data_comps/drof/cime_config/user_nl_drof	src/components/data_comps_mct/drof/cime_config/user_nl_drof
R100	src/components/data_comps/drof/mct/drof_comp_mod.F90	src/components/data_comps_mct/drof/src/drof_comp_mod.F90
R100	src/components/data_comps/drof/mct/drof_shr_mod.F90	src/components/data_comps_mct/drof/src/drof_shr_mod.F90
R100	src/components/data_comps/drof/mct/rof_comp_mct.F90	src/components/data_comps_mct/drof/src/rof_comp_mct.F90
R100	src/components/data_comps/dwav/README	src/components/data_comps_mct/dwav/README
R100	src/components/data_comps/dwav/cime_config/buildlib	src/components/data_comps_mct/dwav/cime_config/buildlib
R100	src/components/data_comps/dwav/cime_config/buildnml	src/components/data_comps_mct/dwav/cime_config/buildnml
R100	src/components/data_comps/dwav/cime_config/config_archive.xml	src/components/data_comps_mct/dwav/cime_config/config_archive.xml
R100	src/components/data_comps/dwav/cime_config/config_component.xml	src/components/data_comps_mct/dwav/cime_config/config_component.xml
R100	src/components/data_comps/dwav/cime_config/namelist_definition_dwav.xml	src/components/data_comps_mct/dwav/cime_config/namelist_definition_dwav.xml
R100	src/components/data_comps/dwav/cime_config/user_nl_dwav	src/components/data_comps_mct/dwav/cime_config/user_nl_dwav
R100	src/components/data_comps/dwav/mct/dwav_comp_mod.F90	src/components/data_comps_mct/dwav/src/dwav_comp_mod.F90
R100	src/components/data_comps/dwav/mct/dwav_shr_mod.F90	src/components/data_comps_mct/dwav/src/dwav_shr_mod.F90
R100	src/components/data_comps/dwav/mct/wav_comp_mct.F90	src/components/data_comps_mct/dwav/src/wav_comp_mct.F90
R100	src/components/stub_comps/satm/cime_config/buildlib	src/components/data_comps_nuopc/datm/cime_config/buildlib
A	src/components/data_comps_nuopc/datm/cime_config/buildnml
A	src/components/data_comps_nuopc/datm/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/datm/cime_config/config_component.xml
A	src/components/data_comps_nuopc/datm/cime_config/namelist_definition_datm.xml
A	src/components/data_comps_nuopc/datm/cime_config/user_nl_datm
R099	src/components/data_comps/datm/nuopc/atm_comp_nuopc.F90	src/components/data_comps_nuopc/datm/src/atm_comp_nuopc.F90
R099	src/components/data_comps/datm/nuopc/datm_comp_mod.F90	src/components/data_comps_nuopc/datm/src/datm_comp_mod.F90
R100	src/components/stub_comps/sesp/cime_config/buildlib	src/components/data_comps_nuopc/dice/cime_config/buildlib
A	src/components/data_comps_nuopc/dice/cime_config/buildnml
A	src/components/data_comps_nuopc/dice/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/dice/cime_config/config_component.xml
A	src/components/data_comps_nuopc/dice/cime_config/namelist_definition_dice.xml
A	src/components/data_comps_nuopc/dice/cime_config/user_nl_dice
R097	src/components/data_comps/dice/nuopc/dice_comp_mod.F90	src/components/data_comps_nuopc/dice/src/dice_comp_mod.F90
R100	src/components/data_comps/dice/nuopc/dice_flux_atmice_mod.F90	src/components/data_comps_nuopc/dice/src/dice_flux_atmice_mod.F90
R099	src/components/data_comps/dice/nuopc/ice_comp_nuopc.F90	src/components/data_comps_nuopc/dice/src/ice_comp_nuopc.F90
R100	src/components/stub_comps/sglc/cime_config/buildlib	src/components/data_comps_nuopc/dlnd/cime_config/buildlib
A	src/components/data_comps_nuopc/dlnd/cime_config/buildnml
A	src/components/data_comps_nuopc/dlnd/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/dlnd/cime_config/config_component.xml
A	src/components/data_comps_nuopc/dlnd/cime_config/namelist_definition_dlnd.xml
A	src/components/data_comps_nuopc/dlnd/cime_config/user_nl_dlnd
R100	src/components/data_comps/dlnd/nuopc/dlnd_comp_mod.F90	src/components/data_comps_nuopc/dlnd/src/dlnd_comp_mod.F90
R100	src/components/data_comps/dlnd/nuopc/lnd_comp_nuopc.F90	src/components/data_comps_nuopc/dlnd/src/lnd_comp_nuopc.F90
R100	src/components/stub_comps/siac/cime_config/buildlib	src/components/data_comps_nuopc/docn/cime_config/buildlib
A	src/components/data_comps_nuopc/docn/cime_config/buildnml
A	src/components/data_comps_nuopc/docn/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/docn/cime_config/config_component.xml
A	src/components/data_comps_nuopc/docn/cime_config/namelist_definition_docn.xml
A	src/components/data_comps_nuopc/docn/cime_config/user_nl_docn
R100	src/components/data_comps/docn/nuopc/docn_comp_mod.F90	src/components/data_comps_nuopc/docn/src/docn_comp_mod.F90
R098	src/components/data_comps/docn/nuopc/ocn_comp_nuopc.F90	src/components/data_comps_nuopc/docn/src/ocn_comp_nuopc.F90
R100	src/components/stub_comps/sice/cime_config/buildlib	src/components/data_comps_nuopc/drof/cime_config/buildlib
A	src/components/data_comps_nuopc/drof/cime_config/buildnml
A	src/components/data_comps_nuopc/drof/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/drof/cime_config/config_component.xml
A	src/components/data_comps_nuopc/drof/cime_config/namelist_definition_drof.xml
A	src/components/data_comps_nuopc/drof/cime_config/user_nl_drof
R100	src/components/data_comps/drof/nuopc/drof_comp_mod.F90	src/components/data_comps_nuopc/drof/src/drof_comp_mod.F90
R100	src/components/data_comps/drof/nuopc/rof_comp_nuopc.F90	src/components/data_comps_nuopc/drof/src/rof_comp_nuopc.F90
R100	src/components/data_comps/dshr_nuopc/dshr_dfield_mod.F90	src/components/data_comps_nuopc/dshr_nuopc/dshr_dfield_mod.F90
R100	src/components/data_comps/dshr_nuopc/dshr_fldlist_mod.F90	src/components/data_comps_nuopc/dshr_nuopc/dshr_fldlist_mod.F90
R100	src/components/data_comps/dshr_nuopc/dshr_methods_mod.F90	src/components/data_comps_nuopc/dshr_nuopc/dshr_methods_mod.F90
R100	src/components/data_comps/dshr_nuopc/dshr_nuopc_mod.F90	src/components/data_comps_nuopc/dshr_nuopc/dshr_nuopc_mod.F90
R100	src/components/stub_comps/slnd/cime_config/buildlib	src/components/data_comps_nuopc/dwav/cime_config/buildlib
A	src/components/data_comps_nuopc/dwav/cime_config/buildnml
A	src/components/data_comps_nuopc/dwav/cime_config/config_archive.xml
A	src/components/data_comps_nuopc/dwav/cime_config/config_component.xml
A	src/components/data_comps_nuopc/dwav/cime_config/namelist_definition_dwav.xml
A	src/components/data_comps_nuopc/dwav/cime_config/user_nl_dwav
R100	src/components/data_comps/dwav/nuopc/dwav_comp_mod.F90	src/components/data_comps_nuopc/dwav/src/dwav_comp_mod.F90
R100	src/components/data_comps/dwav/nuopc/wav_comp_nuopc.F90	src/components/data_comps_nuopc/dwav/src/wav_comp_nuopc.F90
R100	src/components/stub_comps/socn/cime_config/buildlib	src/components/stub_comps_mct/satm/cime_config/buildlib
R100	src/components/stub_comps/satm/cime_config/buildnml	src/components/stub_comps_mct/satm/cime_config/buildnml
R100	src/components/stub_comps/satm/cime_config/config_component.xml	src/components/stub_comps_mct/satm/cime_config/config_component.xml
R100	src/components/stub_comps/satm/mct/atm_comp_mct.F90	src/components/stub_comps_mct/satm/src/atm_comp_mct.F90
R100	src/components/stub_comps/srof/cime_config/buildlib	src/components/stub_comps_mct/sesp/cime_config/buildlib
R100	src/components/stub_comps/sesp/cime_config/buildnml	src/components/stub_comps_mct/sesp/cime_config/buildnml
R100	src/components/stub_comps/sesp/cime_config/config_component.xml	src/components/stub_comps_mct/sesp/cime_config/config_component.xml
R100	src/components/stub_comps/sesp/mct/esp_comp_mct.F90	src/components/stub_comps_mct/sesp/src/esp_comp_mct.F90
R100	src/components/stub_comps/swav/cime_config/buildlib	src/components/stub_comps_mct/sglc/cime_config/buildlib
R100	src/components/stub_comps/sglc/cime_config/buildnml	src/components/stub_comps_mct/sglc/cime_config/buildnml
R100	src/components/stub_comps/sglc/cime_config/config_component.xml	src/components/stub_comps_mct/sglc/cime_config/config_component.xml
R100	src/components/stub_comps/sglc/mct/glc_comp_mct.F90	src/components/stub_comps_mct/sglc/src/glc_comp_mct.F90
R100	src/components/xcpl_comps/xatm/cime_config/buildlib	src/components/stub_comps_mct/siac/cime_config/buildlib
R100	src/components/stub_comps/siac/cime_config/buildnml	src/components/stub_comps_mct/siac/cime_config/buildnml
R100	src/components/stub_comps/siac/cime_config/config_component.xml	src/components/stub_comps_mct/siac/cime_config/config_component.xml
R100	src/components/stub_comps/siac/mct/iac_comp_mct.F90	src/components/stub_comps_mct/siac/src/iac_comp_mct.F90
R100	src/components/xcpl_comps/xglc/cime_config/buildlib	src/components/stub_comps_mct/sice/cime_config/buildlib
R100	src/components/stub_comps/sice/cime_config/buildnml	src/components/stub_comps_mct/sice/cime_config/buildnml
R100	src/components/stub_comps/sice/cime_config/config_component.xml	src/components/stub_comps_mct/sice/cime_config/config_component.xml
R100	src/components/stub_comps/sice/mct/ice_comp_mct.F90	src/components/stub_comps_mct/sice/src/ice_comp_mct.F90
R100	src/components/xcpl_comps/xice/cime_config/buildlib	src/components/stub_comps_mct/slnd/cime_config/buildlib
R100	src/components/stub_comps/slnd/cime_config/buildnml	src/components/stub_comps_mct/slnd/cime_config/buildnml
R100	src/components/stub_comps/slnd/cime_config/config_component.xml	src/components/stub_comps_mct/slnd/cime_config/config_component.xml
R100	src/components/stub_comps/slnd/mct/lnd_comp_mct.F90	src/components/stub_comps_mct/slnd/src/lnd_comp_mct.F90
R100	src/components/xcpl_comps/xlnd/cime_config/buildlib	src/components/stub_comps_mct/socn/cime_config/buildlib
R100	src/components/stub_comps/socn/cime_config/buildnml	src/components/stub_comps_mct/socn/cime_config/buildnml
R100	src/components/stub_comps/socn/cime_config/config_component.xml	src/components/stub_comps_mct/socn/cime_config/config_component.xml
R100	src/components/stub_comps/socn/mct/ocn_comp_mct.F90	src/components/stub_comps_mct/socn/src/ocn_comp_mct.F90
R100	src/components/xcpl_comps/xocn/cime_config/buildlib	src/components/stub_comps_mct/srof/cime_config/buildlib
R100	src/components/stub_comps/srof/cime_config/buildnml	src/components/stub_comps_mct/srof/cime_config/buildnml
R100	src/components/stub_comps/srof/cime_config/config_component.xml	src/components/stub_comps_mct/srof/cime_config/config_component.xml
R100	src/components/stub_comps/srof/mct/rof_comp_mct.F90	src/components/stub_comps_mct/srof/src/rof_comp_mct.F90
R100	src/components/xcpl_comps/xrof/cime_config/buildlib	src/components/stub_comps_mct/swav/cime_config/buildlib
R100	src/components/stub_comps/swav/cime_config/buildnml	src/components/stub_comps_mct/swav/cime_config/buildnml
R100	src/components/stub_comps/swav/cime_config/config_component.xml	src/components/stub_comps_mct/swav/cime_config/config_component.xml
R100	src/components/stub_comps/swav/mct/wav_comp_mct.F90	src/components/stub_comps_mct/swav/src/wav_comp_mct.F90
R100	src/components/xcpl_comps/xwav/cime_config/buildlib	src/components/stub_comps_nuopc/satm/cime_config/buildlib
A	src/components/stub_comps_nuopc/satm/cime_config/buildnml
A	src/components/stub_comps_nuopc/satm/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/sesp/cime_config/buildlib
A	src/components/stub_comps_nuopc/sesp/cime_config/buildnml
A	src/components/stub_comps_nuopc/sesp/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/sglc/cime_config/buildlib
A	src/components/stub_comps_nuopc/sglc/cime_config/buildnml
A	src/components/stub_comps_nuopc/sglc/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/siac/cime_config/buildlib
A	src/components/stub_comps_nuopc/siac/cime_config/buildnml
A	src/components/stub_comps_nuopc/siac/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/sice/cime_config/buildlib
A	src/components/stub_comps_nuopc/sice/cime_config/buildnml
A	src/components/stub_comps_nuopc/sice/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/slnd/cime_config/buildlib
A	src/components/stub_comps_nuopc/slnd/cime_config/buildnml
A	src/components/stub_comps_nuopc/slnd/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/socn/cime_config/buildlib
A	src/components/stub_comps_nuopc/socn/cime_config/buildnml
A	src/components/stub_comps_nuopc/socn/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/srof/cime_config/buildlib
A	src/components/stub_comps_nuopc/srof/cime_config/buildnml
A	src/components/stub_comps_nuopc/srof/cime_config/config_component.xml
A	src/components/stub_comps_nuopc/swav/cime_config/buildlib
A	src/components/stub_comps_nuopc/swav/cime_config/buildnml
A	src/components/stub_comps_nuopc/swav/cime_config/config_component.xml
A	src/components/xcpl_comps_mct/xatm/cime_config/buildlib
R100	src/components/xcpl_comps/xatm/cime_config/buildnml	src/components/xcpl_comps_mct/xatm/cime_config/buildnml
R100	src/components/xcpl_comps/xatm/cime_config/config_component.xml	src/components/xcpl_comps_mct/xatm/cime_config/config_component.xml
R100	src/components/xcpl_comps/xatm/mct/atm_comp_mct.F90	src/components/xcpl_comps_mct/xatm/src/atm_comp_mct.F90
A	src/components/xcpl_comps_mct/xglc/cime_config/buildlib
R100	src/components/xcpl_comps/xglc/cime_config/buildnml	src/components/xcpl_comps_mct/xglc/cime_config/buildnml
R100	src/components/xcpl_comps/xglc/cime_config/config_component.xml	src/components/xcpl_comps_mct/xglc/cime_config/config_component.xml
R100	src/components/xcpl_comps/xglc/mct/glc_comp_mct.F90	src/components/xcpl_comps_mct/xglc/src/glc_comp_mct.F90
A	src/components/xcpl_comps_mct/xice/cime_config/buildlib
R100	src/components/xcpl_comps/xice/cime_config/buildnml	src/components/xcpl_comps_mct/xice/cime_config/buildnml
R100	src/components/xcpl_comps/xice/cime_config/config_component.xml	src/components/xcpl_comps_mct/xice/cime_config/config_component.xml
R100	src/components/xcpl_comps/xice/mct/ice_comp_mct.F90	src/components/xcpl_comps_mct/xice/src/ice_comp_mct.F90
A	src/components/xcpl_comps_mct/xlnd/cime_config/buildlib
R100	src/components/xcpl_comps/xlnd/cime_config/buildnml	src/components/xcpl_comps_mct/xlnd/cime_config/buildnml
R100	src/components/xcpl_comps/xlnd/cime_config/config_component.xml	src/components/xcpl_comps_mct/xlnd/cime_config/config_component.xml
R100	src/components/xcpl_comps/xlnd/mct/lnd_comp_mct.F90	src/components/xcpl_comps_mct/xlnd/src/lnd_comp_mct.F90
A	src/components/xcpl_comps_mct/xocn/cime_config/buildlib
R100	src/components/xcpl_comps/xocn/cime_config/buildnml	src/components/xcpl_comps_mct/xocn/cime_config/buildnml
R100	src/components/xcpl_comps/xocn/cime_config/config_component.xml	src/components/xcpl_comps_mct/xocn/cime_config/config_component.xml
R100	src/components/xcpl_comps/xocn/mct/ocn_comp_mct.F90	src/components/xcpl_comps_mct/xocn/src/ocn_comp_mct.F90
A	src/components/xcpl_comps_mct/xrof/cime_config/buildlib
R100	src/components/xcpl_comps/xrof/cime_config/buildnml	src/components/xcpl_comps_mct/xrof/cime_config/buildnml
R100	src/components/xcpl_comps/xrof/cime_config/config_component.xml	src/components/xcpl_comps_mct/xrof/cime_config/config_component.xml
R100	src/components/xcpl_comps/xrof/mct/rof_comp_mct.F90	src/components/xcpl_comps_mct/xrof/src/rof_comp_mct.F90
R100	src/components/xcpl_comps/xshare/mct/dead_data_mod.F90	src/components/xcpl_comps_mct/xshare/dead_data_mod.F90
R100	src/components/xcpl_comps/xshare/mct/dead_mct_mod.F90	src/components/xcpl_comps_mct/xshare/dead_mct_mod.F90
R100	src/components/xcpl_comps/xshare/mct/dead_mod.F90	src/components/xcpl_comps_mct/xshare/dead_mod.F90
A	src/components/xcpl_comps_mct/xwav/cime_config/buildlib
R100	src/components/xcpl_comps/xwav/cime_config/buildnml	src/components/xcpl_comps_mct/xwav/cime_config/buildnml
R100	src/components/xcpl_comps/xwav/cime_config/config_component.xml	src/components/xcpl_comps_mct/xwav/cime_config/config_component.xml
R100	src/components/xcpl_comps/xwav/mct/wav_comp_mct.F90	src/components/xcpl_comps_mct/xwav/src/wav_comp_mct.F90
A	src/components/xcpl_comps_nuopc/xatm/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xatm/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xatm/cime_config/config_component.xml
R100	src/components/xcpl_comps/xatm/nuopc/atm_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xatm/src/atm_comp_nuopc.F90
A	src/components/xcpl_comps_nuopc/xglc/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xglc/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xglc/cime_config/config_component.xml
R100	src/components/xcpl_comps/xglc/nuopc/glc_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xglc/src/glc_comp_nuopc.F90
A	src/components/xcpl_comps_nuopc/xice/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xice/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xice/cime_config/config_component.xml
R100	src/components/xcpl_comps/xice/nuopc/ice_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xice/src/ice_comp_nuopc.F90
A	src/components/xcpl_comps_nuopc/xlnd/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xlnd/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xlnd/cime_config/config_component.xml
R100	src/components/xcpl_comps/xlnd/nuopc/lnd_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xlnd/src/lnd_comp_nuopc.F90
A	src/components/xcpl_comps_nuopc/xocn/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xocn/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xocn/cime_config/config_component.xml
R100	src/components/xcpl_comps/xocn/nuopc/ocn_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xocn/src/ocn_comp_nuopc.F90
A	src/components/xcpl_comps_nuopc/xrof/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xrof/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xrof/cime_config/config_component.xml
R100	src/components/xcpl_comps/xrof/nuopc/rof_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xrof/src/rof_comp_nuopc.F90
R100	src/components/xcpl_comps/xshare/nuopc/dead_methods_mod.F90	src/components/xcpl_comps_nuopc/xshare/dead_methods_mod.F90
R100	src/components/xcpl_comps/xshare/nuopc/dead_nuopc_mod.F90	src/components/xcpl_comps_nuopc/xshare/dead_nuopc_mod.F90
A	src/components/xcpl_comps_nuopc/xwav/cime_config/buildlib
A	src/components/xcpl_comps_nuopc/xwav/cime_config/buildnml
A	src/components/xcpl_comps_nuopc/xwav/cime_config/config_component.xml
R100	src/components/xcpl_comps/xwav/nuopc/wav_comp_nuopc.F90	src/components/xcpl_comps_nuopc/xwav/src/wav_comp_nuopc.F90
M	src/drivers/mct/cime_config/config_component.xml
M	src/externals/pio2/CMakeLists.txt
M	src/externals/pio2/Makefile.am
A	src/externals/pio2/cmake/Makefile.am
M	src/externals/pio2/configure.ac
M	src/externals/pio2/doc/source/base.txt
M	src/externals/pio2/doc/source/netcdf_integration.txt
M	src/externals/pio2/examples/Makefile.am
M	src/externals/pio2/examples/c/CMakeLists.txt
M	src/externals/pio2/examples/c/Makefile.am
M	src/externals/pio2/examples/c/darray_async.c
M	src/externals/pio2/src/clib/CMakeLists.txt
M	src/externals/pio2/src/clib/Makefile.am
M	src/externals/pio2/src/clib/pio.h
M	src/externals/pio2/src/clib/pio_darray.c
M	src/externals/pio2/src/clib/pio_darray_int.c
M	src/externals/pio2/src/clib/pio_file.c
M	src/externals/pio2/src/clib/pio_internal.h
M	src/externals/pio2/src/clib/pio_lists.c
M	src/externals/pio2/src/clib/pio_msg.c
M	src/externals/pio2/src/clib/pio_nc.c
M	src/externals/pio2/src/clib/pio_rearrange.c
M	src/externals/pio2/src/clib/pioc.c
M	src/externals/pio2/src/clib/pioc_support.c
M	src/externals/pio2/src/flib/Makefile.am
M	src/externals/pio2/src/gptl/Makefile.am
M	src/externals/pio2/src/ncint/ncint_pio.c
M	src/externals/pio2/src/ncint/ncintdispatch.c
M	src/externals/pio2/tests/cunit/CMakeLists.txt
M	src/externals/pio2/tests/cunit/Makefile.am
M	src/externals/pio2/tests/cunit/run_tests.sh
A	src/externals/pio2/tests/cunit/test_async_1d.c
M	src/externals/pio2/tests/cunit/test_darray.c
M	src/externals/pio2/tests/cunit/test_spmd.c
M	src/externals/pio2/tests/fncint/Makefile.am
M	src/externals/pio2/tests/ncint/Makefile.am
A	src/externals/pio2/tests/ncint/pio_err_macros.h
A	src/externals/pio2/tests/ncint/run_perf.sh
M	src/externals/pio2/tests/ncint/run_tests.sh
A	src/externals/pio2/tests/ncint/tst_async_multi.c
A	src/externals/pio2/tests/ncint/tst_ncint_async_perf.c
A	src/externals/pio2/tests/ncint/tst_ncint_perf.c
A	src/externals/pio2/tests/ncint/tst_pio_async.c
M	src/externals/pio2/tests/ncint/tst_pio_udf.c
M	src/externals/pio2/tests/unit/Makefile.am
M	src/share/util/shr_infnan_mod.F90.in
M	tools/cprnc/CMakeLists.txt
billsacks added a commit to billsacks/ctsm that referenced this pull request Mar 28, 2020
@billsacks
Change html build to make versioned documentation with a dropdown menu
d1ea77c 
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 ESMCI/cime#3439,
which in turn was based on ESCOMP/CISM-wrapper#23.
@billsacks billsacks mentioned this pull request Mar 30, 2020
Merged
billsacks added a commit to ESCOMP/CTSM that referenced this pull request Apr 7, 2020
@billsacks
Merge branch 'add_doc_source'
b0610ed 
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
billsacks added a commit to billsacks/ctsm that referenced this pull request Apr 7, 2020
@billsacks
Change html build to make versioned documentation with a dropdown menu
1c2ed61 
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 ESMCI/cime#3439,
which in turn was based on ESCOMP/CISM-wrapper#23.
ekluzek added a commit to ekluzek/CTSM that referenced this pull request Apr 7, 2020
@ekluzek
Merge tag 'ctsm1.0.dev089' into lunadaylbugs
d94ba6f 
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
ekluzek added a commit to ekluzek/CTSM that referenced this pull request Apr 20, 2020
@ekluzek
Merge tag 'ctsm1.0.dev089' into rel2master
741bbd2 
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
jtruesdal added a commit to jtruesdal/ctsm that referenced this pull request May 1, 2020
@jtruesdal
Merge tag 'ctsm1.0.dev089' into fv3port
1e1c60e 
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
@billsacks billsacks mentioned this pull request May 3, 2020
Closed
billsacks added a commit to billsacks/cesm that referenced this pull request Aug 12, 2020
@billsacks
Switch to versioned documentation using sphinx rtd theme
2abbaea 
Follows instructions here
https://drive.google.com/drive/u/0/folders/1WWlz6O1uBPUx7WdgQ24REFnuBrgpCM5U
and here ESMCI/cime#3439
billsacks added a commit to billsacks/cesm that referenced this pull request Aug 12, 2020
@billsacks
Switch to versioned documentation using sphinx rtd theme
c79da0d 
Follows instructions here
https://drive.google.com/drive/u/0/folders/1WWlz6O1uBPUx7WdgQ24REFnuBrgpCM5U
and here ESMCI/cime#3439
@billsacks billsacks mentioned this pull request Aug 12, 2020
Merged
billsacks added a commit to ESCOMP/CESM that referenced this pull request Aug 12, 2020
@billsacks
Merge pull request #164 from billsacks/versioned_docs
934d1a6 
Update documentation format to versioned documentation

Description of changes
Switch to versioned documentation using sphinx rtd theme

Follows instructions here
https://drive.google.com/drive/u/0/folders/1WWlz6O1uBPUx7WdgQ24REFnuBrgpCM5U
and here ESMCI/cime#3439

See the result here: https://escomp.github.io/CESM

Specific notes
Contributors other than yourself, if any: none

Fixes: none

User interface changes?: No

Testing performed (automated tests and/or manual tests): none
fritzt pushed a commit to CESM-GC/CTSM that referenced this pull request May 19, 2021
@billsacks @fritzt
Change html build to make versioned documentation with a dropdown menu
ccfbd5b 
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 ESMCI/cime#3439,
which in turn was based on ESCOMP/CISM-wrapper#23.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rljacob rljacob rljacob approved these changes

@mvertens mvertens mvertens approved these changes

Assignees

@billsacks billsacks

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

Successfully merging this pull request may close these issues.

None yet
5 participants
@billsacks @rljacob @rsdunlapiv @mvertens @jedwards4b