templateflow · oesteban · Sep 8, 2021 · Sep 6, 2021 · Sep 8, 2021
diff --git a/.circleci/config.yml b/.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 gh-pages@2.0.1
-          git config user.email "crn.poldracklab@gmail.com"
-          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:

diff --git a/docs/Makefile b/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/
diff --git a/docs/_templates/versions.html b/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>
diff --git a/docs/conf.py b/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
diff --git a/docs/requirements.txt b/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
diff --git a/setup.cfg b/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 =