DOC: Update docs

Author: effigies

docs/Makefile

@@ -6,7 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
-CURBRANCH     = master
+OUTDIR        = html
 PYTHONPATH    = $(PWD)
 
 # User-friendly check for sphinx-build
@@ -53,10 +53,13 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf reference/*
 
+docs-coverage:
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+
 html:
-	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(OUTDIR)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -179,6 +182,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/_static/css/version-switch.css

@@ -0,0 +1,3 @@
+.version-tree ul {
+	list-style-type: none;
+}

docs/_static/js/version-switch.js

@@ -0,0 +1,41 @@
+$(document).ready(function() {
+    var pathname = window.location.pathname;
+    var cur_ver = $("#version-slug").text().replace(/^[\n\s]+|[\n\s]+$/g, '')
+    var major_minor = "master";
+    if ( cur_ver.lastIndexOf(" (dev)") == -1 ) {
+        major_minor = `${cur_ver.split('.')[0]}.${cur_ver.split('.')[1]}`
+    }
+    var relpath = pathname.substring(pathname.lastIndexOf(major_minor)).replace(/\/$/, '');
+    var levels = relpath.split("/").length - 1
+    if ( levels == 0 ) {
+        levels = 1
+        relpath += "/"
+    }
+    var versions_file = "../".repeat(levels) + "versions.json"
+    relpath = "../".repeat(levels) + relpath
+    relpath = relpath.replace("//", "/")
+    console.log(`relpath="${relpath}", cur_ver="${cur_ver}"`)
+
+    $.getJSON(versions_file, function (data) {
+        $("#version-slug").remove();  // Unnecessary if JSON was downloaded
+
+        $.each(data["tags"].reverse(), function( i, val ) {
+            var new_path = relpath.replace(major_minor, val)
+            var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
+            if ( i == 0 ) {
+                item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Latest Release)</a></li>`
+            }
+            $("#v-tags").append(item)
+        });
+        $.each(data["heads"].reverse(), function( i, val ) {
+            var new_path = relpath.replace(major_minor, val)
+            var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
+            if ( val == "master" ) {
+                item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Development)</a></li>`
+            }
+            $("#v-tags").append(item)
+        });
+    }).fail(function() {
+      $("#version-menu").hide();  // JSON download failed - hide dropdown
+    });
+});

docs/_templates/sidebar/brand.html

@@ -0,0 +1,15 @@
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
+    <span class="sidebar-brand-text">{{ project }}</span>
+    <span id="version-slug" class="sidebar-brand-text">{{ version if version == release else version + ' (dev)' }}</span>
+</a>
+
+<!-- Versions dropdown -->
+<div id="version-menu" class="version-tree">
+  <ul>
+  <li class="toctree-l1 has-children">
+  <span class="sidebar-brand-text">{{ version if version == release else version + ' (dev)' }}</span>
+  <input class="toctree-checkbox" id="toctree-checkbox-v" name="toctree-checkbox-v" role="switch" type="checkbox">
+  <label for="toctree-checkbox-v"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label>
+  <ul id="v-tags"></ul>
+  </ul>
+</div>

docs/api.rst

@@ -6,6 +6,7 @@ Information on specific functions, classes, and methods.
 .. toctree::
    :glob:
 
+   api/sdcflows.cli
    api/sdcflows.interfaces
    api/sdcflows.viz
-   api/sdcflows.workflows
+   api/sdcflows.workflows

docs/conf.py

@@ -1,83 +1,82 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+"""
+Configuration file for the Sphinx documentation builder.
 
-# -- Path setup --------------------------------------------------------------
+This file does only contain a selection of the most common options. For a
+full list see the documentation:
+http://www.sphinx-doc.org/en/master/config
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# 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 sdcflows import __version__, __copyright__, __packagename__
 
-sys.path.append(os.path.abspath('sphinxext'))
+# -- Path setup --------------------------------------------------------------
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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.
+# sys.path.append(os.path.abspath("sphinxext"))
 
 # -- Project information -----------------------------------------------------
 project = __packagename__
 copyright = __copyright__
-author = 'The SDCflows Developers'
+author = "The SDCflows Developers"
 
 # The short X.Y version
 version = Version(__version__).public
 # The full version, including alpha/beta/rc tags
-release = version
-
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
-    'nipype.sphinxext.plot_workflow',
-    'sphinxcontrib.apidoc',
-    'sphinxcontrib.napoleon'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.apidoc",
+    "nipype.sphinxext.apidoc",
+    "nipype.sphinxext.plot_workflow",
 ]
 
 autodoc_mock_imports = [
-    'matplotlib',
-    'nilearn',
-    'nipy',
-    'nitime',
-    'numpy',
-    'pandas',
-    'seaborn',
-    'skimage',
-    'svgutils',
-    'transforms3d',
+    "matplotlib",
+    "nilearn",
+    "nipy",
+    "nitime",
+    "numpy",
+    "pandas",
+    "seaborn",
+    "skimage",
+    "svgutils",
+    "transforms3d",
 ]
 
 # 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'),
+    ("Inputs", "Parameters"),
+    ("Outputs", "Parameters"),
+    ("Attributes", "Parameters"),
+    ("Mandatory Inputs", "Parameters"),
+    ("Optional Inputs", "Parameters"),
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
+
+numfig = True
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -90,9 +89,11 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    '_build', 'Thumbs.db', '.DS_Store',
-    'api/sdcflows.rst',
-    'api/sdcflows.cli.rst', 'api/sdcflows.cli.*.rst']
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "api/sdcflows.rst",
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -103,7 +104,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -114,7 +115,13 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
+html_js_files = [
+    "js/version-switch.js",
+]
+html_css_files = [
+    "css/version-switch.css",
+]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -130,7 +137,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'sdcflowsdoc'
+htmlhelp_basename = "sdcflowsdoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -139,15 +146,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -157,19 +161,21 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'smriprep.tex', 'sMRIPrep Documentation',
-     'The sMRIPrep Developers', 'manual'),
+    (
+        master_doc,
+        "smriprep.tex",
+        "sMRIPrep Documentation",
+        "The sMRIPrep Developers",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'smriprep', 'sMRIPrep Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "smriprep", "sMRIPrep Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -178,9 +184,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'smriprep', 'sMRIPrep Documentation',
-     author, 'sMRIPrep', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "smriprep",
+        "sMRIPrep Documentation",
+        author,
+        "sMRIPrep",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 
@@ -199,21 +211,32 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # -- Extension configuration -------------------------------------------------
 
-apidoc_module_dir = '../sdcflows'
-apidoc_output_dir = 'api'
-apidoc_excluded_paths = ['conftest.py', '*/tests/*', 'tests/*', 'data/*']
+apidoc_module_dir = "../sdcflows"
+apidoc_output_dir = "api"
+apidoc_excluded_paths = ["conftest.py", "*/tests/*", "tests/*", "data/*"]
 apidoc_separate_modules = True
-apidoc_extra_args = ['--module-first', '-d 1', '-T']
+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 = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "bids": ("https://bids-standard.github.io/pybids/", None),
+    "nibabel": ("https://nipy.org/nibabel/", None),
+    "nipype": ("https://nipype.readthedocs.io/en/latest/", None),
+    "niworkflows": ("https://www.nipreps.org/niworkflows/", None),
+    "smriprep": ("https://www.nipreps.org/smriprep/", None),
+    "templateflow": ("https://www.templateflow.org/python-client", None),
+}
 
 # -- Options for versioning extension ----------------------------------------
 scv_show_banner = True