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

Provide a version drop-down menu in documentation #23

Merged
merged 6 commits into from
Dec 9, 2018
Merged

Provide a version drop-down menu in documentation #23

merged 6 commits into from
Dec 9, 2018

Commits on Dec 9, 2018

  1. Squashed 'doc/source/_themes/sphinx_rtd_theme/' content from commit b… 

    …46bba5

git-subtree-dir: doc/source/_themes/sphinx_rtd_theme
git-subtree-split: b46bba51649fd15b90e6938b57a1e96f7063c81f
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    f755c7b View commit details
    Browse the repository at this point in the history

  2. Merge commit 'f755c7b2e9e7efdc50a33ec4fa99d3beee2ca25e' as 'doc/sourc… 

    …e/_themes/sphinx_rtd_theme'
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    d052937 View commit details
    Browse the repository at this point in the history

  3. Avoid including sphinx_rtd_theme files in documentation build 

    Otherwise we get warnings like this:

WARNING: autodoc: failed to import module 'test' from module 'test_py_module'; the following exception was raised:
No module named 'test_py_module'
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:261: WARNING: Footnote [4] is not referenced.
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:267: WARNING: Footnote [11] is not referenced.
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:18: WARNING: Undefined substitution referenced: "problematic".
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:261: WARNING: Unknown target name: "5".
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:304: WARNING: Unknown target name: "body elements".
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/demo.rst:316: WARNING: Unknown target name: "hyperlink reference without a target".
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/README.rst: WARNING: document isn't included in any toctree
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/demo_docs/source/index.rst: WARNING: document isn't included in any toctree
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-basic/index.rst: WARNING: document isn't included in any toctree
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-empty/index.rst: WARNING: document isn't included in any toctree
/Users/sacks/cism-code/cism-wrapper/cism-wrapper_master/doc/source/_themes/sphinx_rtd_theme/tests/roots/test-missing-toctree/index.rst: WARNING: document isn't included in any toctree

See also readthedocs/sphinx_rtd_theme#142
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    82da08b View commit details
    Browse the repository at this point in the history

  4. Get documentation build working with sphinx_rtd_theme 

    The files in _static and _templates were pulled in directly from
marbl-ecosys/MARBL@ddd346f,
without any changes. The changes in conf.py were based on the changes in
that MARBL commit.

A few notes about what seems to be needed:

- It seems that the version and/or release (probably version) listed at
  the top of the file needs to match the string used in
  html_theme_options['versions']

- It seems that we really do need to list every version in
  html_theme_options['versions'] in order for the drop-down menus to be
  created correctly

- This seemed to work regardless of whether I had a versions.json file
  in the build directory

Update 2018-12-08: The above notes are no longer true now that I have
the javascript working correctly (with correct paths for our
documentation build), as I fixed in a later commit on this branch.
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    3d975e8 View commit details
    Browse the repository at this point in the history

  5. Update instructions for latest versioned_doc_builder 

    - No longer have an -i argument (now just specify that via extra path
  elements in the -r argument)

- Now have a versions subdirectory
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    72e1dc6 View commit details
    Browse the repository at this point in the history

  6. Get javascript working for our directory structure, and other fixes 

    A key difference driving some of these changes is that, with our
directory structure, there is an extra 'html' subdirectory in the paths.

Specific changes are:

- In conf.py: Add '_static' to html_static_path. This is needed in order
  to copy the javascript into the build

- In conf.py: Set the initial values of 'versions' in a way that can
  stay the same for all branches. Note that these initial values aren't
  really important, because they will be replaced by the javascript.

- In footer.html: Change the path to be correct given this extra 'html'
  subdirectory in the paths

- In pop_ver.js: Get rid of the startsWith/substring logic that wasn't
  doing anything (as far as I can tell). Instead, leverage a "smarter"
  versions.json file that provides any desired renames. See below for
  the file I'm currently using.

- In pop_ver.js: Fix the URLs to be correct for our directory structure,
  which has 'html' in the paths.

- In pop_ver.js: Fix the URL for the current version. This doesn't seem
  to be important in most cases: since the current version starts out
  being the selected version, clicking on it doesn't do
  anything. However, the old, incorrect link caused problems in Firefox
  when I navigated to a page in a certain version, then clicked on a
  different version, then hit back (at this point, the version in the
  menu was the different version), then clicked on the current version:
  this gave a page not found error.

- In pop_ver.js: Add a bunch of comments

I currently have the following versions.json file in the 'versions'
subdirectory of the documentation build; note that this now maps a
directory name onto a version name:

{
    "master": "master",
    "release-cesm2.0": "CESM2.0",
    "release-cesm2.1": "CESM2.1"
}

(Note that the separate CESM2.0 vs. CESM2.1 was just done for the
purposes of testing to make sure we could add a third version that isn't
explicitly listed in conf.py: in reality we still just have a single
release version of the documentation.)
    @billsacks
    billsacks committed Dec 9, 2018
    Configuration menu
    Copy the full SHA
    0a67919 View commit details
    Browse the repository at this point in the history