Merge pull request #368 from ExaWorks/docs_multiversion

Docs multiversion

Author: hategan

Makefile

@@ -44,7 +44,7 @@ stylecheck:
 	flake8 src tests
 
 .PHONY: checks
-checks: typecheck stylecheck
+checks: typecheck stylecheck docs
 
 .PHONY: docs
 docs:
@@ -56,7 +56,8 @@ docs:
 .PHONY: web-docs
 web-docs:
 	rm -rf docs/.generated
-	sphinx-build -W -b html -D html_theme='cloud' -D templates_path='_templates' docs docs/.web-build/
+	rm -rf docs/.web-build
+	PSIJ_WEB_DOCS=1 sphinx-multiversion docs docs/.web-build
 
 .PHONY: style
 style:

docs/_templates/layout.html

@@ -16,6 +16,11 @@
         {{ super() }}
 {% endblock %}
 
+{% block rootrellink %}
+    <li><a href="{{ pathto(theme_roottarget) }}">{{shorttitle|e}}</a>{% if versions %}{% include "../../web/_includes/versionselect.html" %}{% endif %}{{reldelim1}}</li>
+{% endblock %}
+
+
 {% block footer %}
         {{ super() }}
 

docs/conf.py

@@ -8,16 +8,22 @@
 import sphinx_rtd_theme
 from sphinx.ext.apidoc import main
 
+web_docs = False
+if 'PSIJ_WEB_DOCS' in os.environ:
+	web_docs = True
+
 needs_sphinx = '1.6'
 
 # Set Sphinx variables
 master_doc = 'index'
 
 project = u'PSI/J'
 copyright = u'The ExaWorks Team'
-
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+if web_docs:
+	html_theme = 'cloud'
+else:
+	html_theme = 'sphinx_rtd_theme'
+	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_favicon = 'favicon.ico'
 autoclass_content = 'both'
 add_module_names = False
@@ -28,6 +34,25 @@
     ('py:class', 'distutils.version.Version')
 ]
 
+if web_docs:
+    templates_path = ['_templates']
+    # Unfortunately sphinx-multiversion does not properly deal with 
+    # setting the title to the proper version. You either get some
+    # default like "0.0.1" or you get whatever the current conf.py
+    # sets (i.e., the latest version).
+    # See, e.g., https://github.com/Holzhaus/sphinx-multiversion/issues/61
+    #
+    # But we already have the version selector that displays the version,
+    # so we can display that where the broken version would otherwise
+    # have appeared.
+    html_title = "PSI/J"
+    # Multi-version
+    smv_branch_whitelist = '^matchmeifyoucan$'
+    smv_remote_whitelist = None
+    smv_released_pattern = r'^\d+\.\d+\.\d+(\..*)?$'
+    smv_outputdir_format = 'v/{ref.name}'
+
+
 html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}
 
 # These are needed for the dhtml trickery
@@ -44,20 +69,29 @@
     'sphinx.ext.viewcode',
 ]
 
+if web_docs:
+    extensions.append('sphinx_multiversion')
+
 autodoc_typehints = "description"
 autodoc_typehints_format = "short"
 
+release = None
+version = None
+src_dir = None
+
+def read_version(docs_dir):
+    global release, version, src_dir
+    src_dir = os.path.abspath(os.path.join(docs_dir, '../src'))
 
-script_dir = os.path.normpath(os.path.dirname(__file__))
-src_dir = os.path.abspath(os.path.join(script_dir, '../src'))
+    sys.path.insert(0, src_dir)
 
-print(src_dir + "/")
+    import psij
+    release = psij.__version__
+    version = release
 
-sys.path.insert(0, src_dir)
 
-import psij
-release = psij.__version__
-version = release
+my_dir = os.path.normpath(os.path.dirname(__file__))
+read_version(my_dir)
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
@@ -69,10 +103,9 @@
 # Copied from https://github.com/readthedocs/readthedocs.org/issues/1139
 
 # run api doc
-def run_apidoc(_):
-    output_path = os.path.join(script_dir, '.generated')
-    print(f"OUTPUT PATH = {output_path}")
-    #exclusions = [os.path.join(src_dir, 'setup.py'),]
+def run_apidoc(sphinx):
+    read_version(sphinx.srcdir)  # this sets src_dir based on the version being compiled
+    output_path = os.path.join(sphinx.srcdir, '.generated')
     main(['-f', '-o', output_path, src_dir])
 
 # launch setup

requirements-docs.txt

@@ -10,6 +10,7 @@ six
 Sphinx==4.5.0
 sphinx_rtd_theme
 sphinx-tabs
+sphinx-multiversion
 
 # For the web version of the docs
 cloud_sptheme == 1.10.1.post20200504175005

web/_includes/head.html

@@ -16,3 +16,5 @@
     <link rel="stylesheet"
         href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.4.0/styles/base16/tender.min.css">
     <script src="https://kit.fontawesome.com/0f2ef02e2b.js" crossorigin="anonymous"></script>
+    <script src="{{ site.baseurl }}/versions.js"></script>
+    <script src="{{ site.baseurl }}/versioning.js"></script>

web/_includes/versionselect.html

@@ -0,0 +1,3 @@
+            <div id="version-selector">
+                <v-select :items="getSortedVersionLabels()" @change="setVersion" v-model="version"></v-select>
+            </div>

web/_includes/vueinit.html

@@ -4,7 +4,12 @@
             el: '#psij-app',
             vuetify: new Vuetify(),
             data: {
-                maintabs: {{ page.tab }}
+                maintabs: {{ page.tab }},
+                version: getCurrentVersion()
+            },
+            methods: {
+                getSortedVersionLabels: getSortedVersionLabels,
+                setVersion: setVersion
             }
         });
 

web/build.sh

@@ -18,8 +18,26 @@ if [ "$1" != "--quick" ]; then
 	cp -r docs/.web-build/. web-build/docs/
 fi
 
-cp -r web/. web-build/
-cp web/*.css web-build/docs/
+
+cp -r web/_layouts/ web-build/
+cp -r web/_includes/ web-build/
+
+echo -n "var DOC_VERSIONS_RAW = [" >web-build/versions.js
+for V in `ls web-build/docs/v`; do
+	echo "Patching version $V"
+	cp -r web/docs/_static web-build/docs/v/$V/
+
+	echo "\"$V\", " >>web-build/versions.js
+done
+echo "]" >>web-build/versions.js
+
+for F in `ls web/*`; do
+	if [ -f "$F" ]; then
+		cp "$F" web-build/
+	fi
+done
+
+cp web/docs/index.html web-build/docs/
 
 rm -f web-build/*.sh
-rm -f web-build/README
+rm -f web-build/README

web/docs/_static/cloud.css

@@ -40,6 +40,7 @@ ul, ol {
 
 div.relbar-top {
     background-color: #e0e0e0;
+    border-bottom: 1px solid var(--color-fg-lines);
 }
 
 
@@ -112,7 +113,7 @@ div.body {
 }
 
 div.sphinxsidebar {
-    margin-top: 32pt;
+    margin-top: 4pt;
     width: 3in;
     font-size: 90%;
     line-height: 1.25em;
@@ -123,7 +124,7 @@ div.document.sidebar-hidden div.sphinxsidebar {
 }
 
 div.sphinxsidebarwrapper {
-    padding: 1em 0 0 10px;
+    padding: 0 0 0 10px;
 }
 
 div.sphinxsidebar h3, div.sphinxsidebar h4 {

web/docs/index.html

@@ -0,0 +1,29 @@
+---
+title: PSI/J - Python
+layout: raw
+tab: 2
+---
+
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Documentation - PSI/J - Python</title>
+        <script src="{{ site.baseurl }}/versions.js"></script>
+        <script src="{{ site.baseurl }}/versioning.js"></script>
+    </head>
+    <body>
+        <script type="application/javascript">
+            var latest = getLatestVersion();
+            document.write("Redirecting to <a href=\"v/" + latest + "\">Version " + latest + " documentation</a>");
+            var loc = window.location.href;
+            if (loc.endsWith(".html")) {
+                loc = loc.substring(0, loc.lastIndexOf("/"));
+            }
+            if (loc.endsWith("/")) {
+                loc = loc.substring(0, loc.length - 1);
+            }
+            window.location = loc + "/v/" + latest + "/";
+        </script>
+    </body>
+</html>
+