Updates to documentation build for maint56 #3455
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
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
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.
Add pip install commands, remove some pieces that are no longer correct.
Rationale: The api documentation is built in the source tree. This leads to a high potential for accidentally building the documentation using a different version of the api documentation, if you have a build already sitting around from a different branch and you forget to run 'make api' before running 'make html' (I find myself making that mistake). We mitigate this risk by ensuring that 'clean_api' is run whenever 'make clean' is run, and having 'clean_api' remove any pre-existing generated api documentation.
This way we don't need to remember to rerun 'make api' before running 'make html'. This is also needed when using https://github.com/ESMCI/versioned-doc-builder with the '--clean' flag (with the last commit, that made 'make clean' also run 'clean_api'): otherwise, the api documentation gets cleaned and never rebuilt in time to make the html documentation. This makes the new 'clean_api' somewhat less important, but it still seems good to have that in place, so that a 'make clean' also cleans out the generated api documentation.
|
@jedwards4b note that these changes are identical to ones that have already been approved for master. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Includes the changes in #3439 and #3454 , but for the maint-5.6 branch.
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: