sphinx-multiversion to replace sphinxcontrib-versioning?

doc/_templates/versioning.html

@@ -0,0 +1,14 @@
+{% if versions %}
+<h4>{{ _('Latest Version') }}</h4>
+<ul>
+  {%- for item in versions.branches %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+<h4>{{ _('Older Versions') }}</h4>
+<ul>
+  {%- for item in versions.tags %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+{% endif %}

doc/_themes/flask_local/layout.html

@@ -28,7 +28,7 @@ <h1><a href="http://clawpack.org/">Clawpack-5</a></h1>
           <a href="{{ pathto("installing") }}">Install</a>
         </li>
         <li>
-          <a class="" href="{{ pathto("../../../gallery/_build/html/index") }}">Gallery</a>
+          <a class="" href="http://clawpack.org/gallery">Gallery</a>
         </li>
         <li>
           <a class="" href="{{ pathto("community") }}">Community</a>

doc/conf.py

@@ -40,10 +40,11 @@
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
               'sphinx.ext.intersphinx',#'plot_directive',
-              'only_directives',
-              'sphinx.ext.inheritance_diagram']
+              'only_directives', # 'edit_on_github', # broken
+              'sphinx.ext.inheritance_diagram', 'nbsphinx',
+              'sphinx_multiversion']
 
-nbsphinx_allow_errors = False
+nbsphinx_allow_errors = True
 
 extensions.append('sphinx.ext.mathjax')
 mathjax_path = 'http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
@@ -52,10 +53,11 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 edit_on_github_project = 'clawpack/doc'
-edit_on_github_branch = 'master/doc'
+edit_on_github_branch = 'master/dev'
 
 # The encoding of source files.
 #source_encoding = 'utf-8'
@@ -128,11 +130,25 @@
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    'index':    ['localtoc.html', 'sourcelink.html', 'searchbox.html'],
+    'index':    ['localtoc.html', 'sourcelink.html', 'searchbox.html',
+                 'versioning.html'],
     '**':       ['localtoc.html', 'relations.html',
-                 'sourcelink.html', 'searchbox.html']
+                 'sourcelink.html', 'searchbox.html', 'versioning.html']
 }
 
+# Whitelist pattern for tags (set to None to ignore all tags)
+# Will show up in list of Older releases,  see _templates/versioning.html
+smv_tag_whitelist = r'^.*$'  # all tags 
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+# Will show up in list of Latest releases,  see _templates/versioning.html
+smv_branch_whitelist = r'v5.6.1|dev'    # r'^.*$'
+
+# For possible use in adding version banners?
+# see https://holzhaus.github.io/sphinx-multiversion/master/templates.html#version-banners
+smv_released_pattern = r'v.*'
+smv_latest_version = 'v5.6.1'
+
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 #html_theme = 'default'

doc/fix_links_top_level.py

@@ -0,0 +1,50 @@
+
+"""
+Script to use with this code for making multi-version docs:
+    https://holzhaus.github.io/sphinx-multiversion/master/index.html
+
+Using sphinx-multiversion creates a _build/html directory that has a
+subdirectory for each version.  But the current version .html files are not
+in _build/html so you can only reach them if you point to a specific version.
+
+We copy _build/html/* to $CLAW/clawpack.github.org/ for hosting on the web.
+
+We want e.g. www.clawpack.org/installing.html to point to the current release
+(without having to specify e.g.  www.clawpack.org/v5.6.1/installing.html).
+This can be accomplished by copying the v5.6.1/* files up a level, but then the
+links in the sidebar don't work properly for reaching other versions.
+
+This script fixes those links.
+
+First do:
+
+    sphinx-multiversion . _build/html
+
+This creates _build/html/dev and _build_html/v5.* for each branch/tag
+
+Then copy the files from the current release up a level and fix the links
+from these files to other versions:
+
+    cd _build/html
+    cp -r v5.6.1/* .   # Note: replace v5.6.1 with current version
+    python ../../fix_links_top_level.py
+
+This changes the links in the sidebar that point to other versions, replacing
+../dev with ./dev, for example.
+
+"""
+
+import os,sys,glob
+
+files = glob.glob('*.html')
+for file in files:
+    lines = open(file,'r').readlines()
+    with open(file,'w') as f:
+        for line in lines:
+            line = line.replace('../v5','./v5')
+            line = line.replace('../dev','./dev')
+            f.write(line)
+
+    print('Done with %s' % file)
+
+

doc/rsync_sampledocs.sh

@@ -3,5 +3,5 @@
 
 chmod -R og+rX _build
 rsync -avz --delete _build/html/ \
-  [email protected]:public_html/sampledocs/v5.5.0alpha/
+  [email protected]:public_html/sampledocs/sphinx-multiversion/