From 3ad7f9106bf204b18fd78efcd5a7ae32ae8c8828 Mon Sep 17 00:00:00 2001
From: Randy LeVeque <rjl@uw.edu>
Date: Sun, 5 Apr 2020 15:54:35 -0700
Subject: [PATCH 1/4] update conf.py to use sphinx-multiversion

---
 doc/_templates/versioning.html | 14 ++++++++++++++
 doc/conf.py                    | 23 +++++++++++++++++------
 2 files changed, 31 insertions(+), 6 deletions(-)
 create mode 100644 doc/_templates/versioning.html

diff --git a/doc/_templates/versioning.html b/doc/_templates/versioning.html
new file mode 100644
index 0000000..f9b8d48
--- /dev/null
+++ b/doc/_templates/versioning.html
@@ -0,0 +1,14 @@
+{% if versions %}
+<h3>{{ _('Latest') }}</h3>
+<ul>
+  {%- for item in versions.branches %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+<h3>{{ _('Older') }}</h3>
+<ul>
+  {%- for item in versions.tags %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+{% endif %}
diff --git a/doc/conf.py b/doc/conf.py
index 523334b..05b8549 100644
--- a/doc/conf.py
+++ b/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,20 @@
 
 # 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'^.*$'
+
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
 #html_theme = 'default'

From 762fdcfa1d6d253068ce1cefdc5895ff472ca561 Mon Sep 17 00:00:00 2001
From: Randy LeVeque <rjl@uw.edu>
Date: Mon, 6 Apr 2020 10:58:06 -0700
Subject: [PATCH 2/4] some updates to sphinx-multiversion sidebar look

---
 doc/_templates/versioning.html | 4 ++--
 doc/conf.py                    | 5 +++++
 doc/rsync_sampledocs.sh        | 2 +-
 3 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/_templates/versioning.html b/doc/_templates/versioning.html
index f9b8d48..0b019f5 100644
--- a/doc/_templates/versioning.html
+++ b/doc/_templates/versioning.html
@@ -1,11 +1,11 @@
 {% if versions %}
-<h3>{{ _('Latest') }}</h3>
+<h4>{{ _('Latest Version') }}</h4>
 <ul>
   {%- for item in versions.branches %}
   <li><a href="{{ item.url }}">{{ item.name }}</a></li>
   {%- endfor %}
 </ul>
-<h3>{{ _('Older') }}</h3>
+<h4>{{ _('Older Versions') }}</h4>
 <ul>
   {%- for item in versions.tags %}
   <li><a href="{{ item.url }}">{{ item.name }}</a></li>
diff --git a/doc/conf.py b/doc/conf.py
index 05b8549..614fa66 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -144,6 +144,11 @@
 # 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'
diff --git a/doc/rsync_sampledocs.sh b/doc/rsync_sampledocs.sh
index 66946de..61c366a 100644
--- a/doc/rsync_sampledocs.sh
+++ b/doc/rsync_sampledocs.sh
@@ -3,5 +3,5 @@
 
 chmod -R og+rX _build
 rsync -avz --delete _build/html/ \
-  clawpack@homer.u.washington.edu:public_html/sampledocs/v5.5.0alpha/
+  clawpack@homer.u.washington.edu:public_html/sampledocs/sphinx-multiversion/
 

From 7a1e33624ad21cf50be93b48bd6b7ee00256531d Mon Sep 17 00:00:00 2001
From: Randy LeVeque <rjl@uw.edu>
Date: Mon, 6 Apr 2020 10:58:27 -0700
Subject: [PATCH 3/4] hardwire link to gallery rather than relative link

---
 doc/_themes/flask_local/layout.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/_themes/flask_local/layout.html b/doc/_themes/flask_local/layout.html
index b5c5fd5..79ba57a 100644
--- a/doc/_themes/flask_local/layout.html
+++ b/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>

From d31e69c98452727141960f74d1b9242dc804bf67 Mon Sep 17 00:00:00 2001
From: Randy LeVeque <rjl@uw.edu>
Date: Mon, 6 Apr 2020 10:59:06 -0700
Subject: [PATCH 4/4] script fix_links_top_level.py for top level sidebar links

---
 doc/fix_links_top_level.py | 50 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 doc/fix_links_top_level.py

diff --git a/doc/fix_links_top_level.py b/doc/fix_links_top_level.py
new file mode 100644
index 0000000..6792b71
--- /dev/null
+++ b/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)
+    
+