MAINT: Discontinue use of sphinxcontrib-versioning (#78)

* wip

* fix: new approach to multiversioned docs

This PR relies on a little javascript to create the dropdown menu to
select the version.
The sphinxcontrib-versioning package is not anymore used, and the
different versions of documentation are just accumulated on the
`gh-pages` branch of the repo.
Therefore, all versions are not built anymore with every build.
The new approach completely decouples the generation of versions
of documentation from the chooser, allowing us flexibility to change
themes or completely change the structure, so long the new theme or
documentation scheme is capable of interpreting the `versions.json` file
at the root of `gh-pages`.

Author: oesteban

.circleci/config.yml

@@ -1,26 +1,3 @@
-docs_deploy: &docs
-  docker:
-    - image: node:8.10.0
-  steps:
-    - checkout
-    - attach_workspace:
-        at: docs/_build
-    - run:
-        name: Disable jekyll builds
-        command: touch docs/_build/html/.nojekyll
-    - run:
-        name: Install and configure dependencies
-        command: |
-          npm install -g --silent [email protected]
-          git config user.email "[email protected]"
-          git config user.name "ci-build"
-    - add_ssh_keys:
-        fingerprints:
-          - "ae:95:0c:cc:09:84:64:99:92:82:b7:b5:f4:a7:e9:23"
-    - run:
-        name: Deploy docs to gh-pages branch
-        command: gh-pages --dotfiles --message "doc(update) [skip ci]" --dist docs/_build/html
-
 version: 2
 jobs:
   tests:
@@ -149,14 +126,6 @@ jobs:
       - FSLOUTPUTTYPE: NIFTI
       - SUBJECTS_DIR: /tmp/subjects
     steps:
-      - restore_cache:
-          keys:
-            - docs-v1-{{ .Branch }}-{{ .Revision }}
-            - docs-v1-{{ .Branch }}-
-            - docs-v1-master
-            - docs-v1-
-          paths:
-            - ./docs/_build/_html
       - checkout
       - run:
           name: Create subjects folder
@@ -173,30 +142,9 @@ jobs:
           name: Build only this commit
           command: |
             python setup.py --version
-            make -C docs SPHINXOPTS="-W" BUILDDIR="_build/no_version_html" html
+            make -C docs SPHINXOPTS="-W" BUILDDIR="/docs" CURBRANCH="${CIRCLE_TAG}" html
       - store_artifacts:
-          path: ./docs/_build/no_version_html
-      - run:
-          name: Generate Versioned Docs
-          command: |
-            set +e
-            force_versioned="$( git log --format=oneline -n 1 $CIRCLE_SHA1 | grep -i -E '\[docs?[ _]?versions?\]' )"
-            set -e
-            if [[ "x${CIRCLE_TAG}" = "x" && "${CIRCLE_BRANCH}" != "master" && "x${force_versioned}" = "x" ]]; then
-              echo "Not a tag or master branch - skipping versioned docs."
-              circleci step halt
-            else
-              make -f ./docs/Makefile versioned CURBRANCH=${CIRCLE_TAG:-$CIRCLE_BRANCH}
-            fi
-      - save_cache:
-          key: docs-v1-{{ .Branch }}-{{ .Revision }}
-          paths:
-            - ./docs/_build/_html
-      - persist_to_workspace:
-          root: docs/_build
-          paths: html
-      - store_artifacts:
-          path: ./docs/_build/html
+          path: /docs/
 
   deploy_pypi:
     docker:
@@ -224,12 +172,6 @@ jobs:
             twine check dist/*
             twine upload dist/*
 
-  deploy_docs_tag:
-    <<: *docs
-
-  deploy_docs_master:
-    <<: *docs
-
 workflows:
   version: 2
   build_test_deploy:
@@ -243,7 +185,7 @@ workflows:
               only: /.*/
       - deploy_pypi:
           requires:
-            - deploy_docs_tag
+            - build_docs
           filters:
             branches:
               ignore: /.*/
@@ -258,26 +200,6 @@ workflows:
             tags:
               only: /.*/
 
-      - deploy_docs_master:
-          requires:
-            - tests
-            - build_docs
-          filters:
-            branches:
-              only: /master/
-            tags:
-              ignore: /.*/
-
-      - deploy_docs_tag:
-          requires:
-            - tests
-            - build_docs
-          filters:
-            branches:
-              ignore: /.*/
-            tags:
-              only: /.*/
-
   nightly:
     triggers:
       - schedule:

docs/Makefile

@@ -55,9 +55,17 @@ clean:
 	rm -rf api/*
 
 html:
-	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	mkdir -p $(BUILDDIR)
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(CURBRANCH)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/."
+
+
+versioned:
+	mkdir -p $(BUILDDIR)
+	PYTHONPATH=$(PYTHONPATH) sphinx-multiversion -v . $(BUILDDIR)/
+	@echo
+	@echo "Multi-version build finished. The HTML pages are in $(BUILDDIR)/."	
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -180,6 +188,3 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-versioned:
-	PYTHONPATH=$(PYTHONPATH) sphinx-versioning -vv -l ./docs/conf.py build -r $(CURBRANCH) ./docs/ docs/$(BUILDDIR)/html/

docs/_templates/versions.html

@@ -0,0 +1,36 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ version }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div id="version-switch" class="rst-other-versions">
+    <dt id="v-tags"></dt>
+    <dt id="v-branches"></dt>
+  </div>
+</div>
+
+<script type="text/javascript">
+$(document).ready(function() {
+    var pathname = window.location.pathname;
+    var cur_ver = "/{{ current_version.name if current_version else 'master' }}/"
+    var relpath = pathname.substring(pathname.indexOf(cur_ver) + 1).replace(/\/$/, '');
+    var levels = relpath.split("/").length - 1
+    if ( levels == 0 ) {
+        levels = 1
+	relpath += "/"
+    }
+    var versions_file = "../".repeat(levels) + "versions.json"
+    relpath = "../".repeat(levels) + relpath
+    console.log(`relative path: "${relpath}"`)
+
+    $.getJSON(versions_file, function (data) {
+
+        $.each(data["tags"], function( i, val ) {
+            $("#v-tags").append("<dd><a href=\"" + relpath.replace(cur_ver, "/" + val + "/") + "\">" + val + "</a></dd>")
+        });
+        $("#v-branches").append("<dd><a href=\"" + relpath.replace(cur_ver, "/" + data["tags"][data["tags"].length - 1]+ "/") + "\">latest</a></dd>")
+        $("#v-branches").append("<dd><a href=\"" + relpath.replace(cur_ver, "/master/") + "\">dev</a></dd>")
+    });
+});
+</script>

docs/conf.py

@@ -10,37 +10,36 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
 from packaging.version import Version
-
 from templateflow import __version__, __copyright__, __packagename__
 
-sys.path.append(os.path.abspath("sphinxext"))
-
 # -- Project information -----------------------------------------------------
 project = __packagename__
 copyright = __copyright__
 author = "The TemplateFlow Developers"
 
-# The short X.Y version
-version = Version(__version__).public
 # The full version, including alpha/beta/rc tags
 release = __version__
 
+# The short X.Y version
+version = (
+    __version__ if Version(release).public == release
+    else f"dev ({release.partition('+')[0]})"
+)
 
 # -- General configuration ---------------------------------------------------
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
     "sphinx.ext.doctest",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.ifconfig",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
-    "sphinx.ext.ifconfig",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
     "sphinxcontrib.apidoc",
-    "sphinxcontrib.napoleon",
+    "sphinx_multiversion",
 ]
 
 autodoc_mock_imports = [
@@ -55,16 +54,17 @@
     "svgutils",
     "transforms3d",
 ]
+autodoc_autoreload = True
 
 # Accept custom section names to be parsed for numpy-style docstrings
 # of parameters.
 # Requires pinning sphinxcontrib-napoleon to a specific commit while
 # https://github.com/sphinx-contrib/napoleon/pull/10 is merged.
-napoleon_use_param = False
-napoleon_custom_sections = [
-    ("Inputs", "Parameters"),
-    ("Outputs", "Parameters"),
-]
+# napoleon_use_param = False
+# napoleon_custom_sections = [
+#     ("Inputs", "Parameters"),
+#     ("Outputs", "Parameters"),
+# ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -213,14 +213,31 @@
 
 apidoc_module_dir = "../templateflow"
 apidoc_output_dir = "api"
-apidoc_excluded_paths = ["conftest.py", "*/tests/*", "tests/*", "data/*"]
+apidoc_excluded_paths = [
+    "conftest.py",
+    "*/tests/*",
+    "tests/*",
+    "data/*",
+]
 apidoc_separate_modules = True
 apidoc_extra_args = ["--module-first", "-d 1", "-T"]
 
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {
+    "bids": ("https://bids-standard.github.io/pybids/", None),
+    "matplotlib": ("https://matplotlib.org/", None),
+    "nibabel": ("https://nipy.org/nibabel/", None),
+    "nipype": ("https://nipype.readthedocs.io/en/latest/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None),
+    "python": ("https://docs.python.org/3/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+}
 
 # -- Options for versioning extension ----------------------------------------
-scv_show_banner = True
+smv_branch_whitelist = r"^master$"
+smv_tag_whitelist = r"^\d+\.\d+\.\d+(?!rc|dev).*$"
+smv_released_pattern = r'^tags/.*$'
+smv_rebuild_tags = False

docs/requirements.txt

@@ -1,13 +1,12 @@
-git+https://github.com/AleksandarPetrov/napoleon.git@0dc3f28a309ad602be5f44a9049785a1026451b3#egg=sphinxcontrib-napoleon
-git+https://github.com/rwblair/sphinxcontrib-versioning.git@39b40b0b84bf872fc398feff05344051bbce0f63#egg=sphinxcontrib-versioning
 nbsphinx
 packaging
 pybids>=0.11.1
 pydot>=1.2.3
 pydotplus
 requests
 sphinx-argparse
-sphinx>=2.1.2
-sphinx_rtd_theme
-sphinxcontrib-apidoc ~= 0.3.0
+sphinx ~= 4.0
+sphinx_rtd_theme >= 0.4.3
+sphinxcontrib-apidoc
+sphinx_multiversion
 tqdm

setup.cfg

@@ -61,11 +61,10 @@ doc =
     pydot>=1.2.3
     pydotplus
     sphinx-argparse
-    sphinx>=2.1.2
-    sphinx_rtd_theme
-    sphinxcontrib-apidoc ~= 0.3.0
-    sphinxcontrib-napoleon
-    sphinxcontrib-versioning
+    sphinx ~= 4.0
+    sphinx_rtd_theme >= 0.4.3
+    sphinxcontrib-apidoc
+    sphinx_multiversion
 docs =
     %(doc)s
 test =