[DOC]: Improve Sphinx configuration and extensions

.github/workflows/ci.yml

@@ -93,16 +93,11 @@ jobs:
       continue-on-error: true
     - name: Install FSL
       run: |
-        curl -fsSL https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py | python - -d /opt/fsl/
-        FSLOUTPUTTYPE="NIFTI_GZ"
-        FSLMULTIFILEQUIT="TRUE"
-        FSLTCLSH="/opt/fsl/bin/fsltclsh"
-        FSLWISH="/opt/fsl/bin/fslwish"
-        FSLLOCKDIR=""
-        FSLMACHINELIST=""
-        FSLREMOTECALL=""
-        FSLGECUDAQ="cuda.q"
-        echo "/opt/fsl" >> $GITHUB_PATH
+        curl -fsSL https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py | python - -d /opt/fsl/ --skip_registration
+        echo "FSLDIR=/opt/fsl" >> $GITHUB_ENV
+        echo "FSLOUTPUTTYPE=NIFTI_GZ" >> $GITHUB_ENV
+        echo "FSLMULTIFILEQUIT=TRUE" >> $GITHUB_ENV
+        echo "/opt/fsl/bin" >> $GITHUB_PATH
       if: matrix.python-version == 3.11
       # Bypass FSL installation failure
       continue-on-error: true

docs/Makefile

@@ -19,24 +19,14 @@ clean:
 	rm -rf auto_examples/
 	rm -rf api/generated/
 
-# For local build
-local: news
-	make _build_local; STATUS=$$?; make news_cleanup; exit $$STATUS
-
-news:
-	@echo "Generating whats_new.rst"
-	cd ../ && towncrier build --keep
-
-news_cleanup:
-	@echo "Cleaning up whats_new.rst"
-	git restore --staged whats_new.rst
-	git restore whats_new.rst
+local:
+	make _build_local; STATUS=$$?; exit $$STATUS
 
 _build_local:
 	sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-html: news
-	make _html; STATUS=$$?; make news_cleanup; exit $$STATUS
+html:
+	make _html; STATUS=$$?; exit $$STATUS
 
 _html:
 	$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

docs/changes/newsfragments/358.doc

@@ -0,0 +1 @@
+Improve Sphinx configuration and extensions by `Synchon Mandal`_

docs/conf.py

@@ -6,53 +6,65 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- 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.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-import sys
+import datetime
+from functools import partial
 from pathlib import Path
 
+from setuptools_scm import get_version
+
 
 # Check if sphinx-multiversion is installed
 use_multiversion = False
 try:
     import sphinx_multiversion  # noqa: F401
+
     use_multiversion = True
 except ImportError:
     pass
 
-curdir = Path(__file__).parent
-sys.path.append((curdir / "sphinxext").as_posix())
+
+# -- Path setup --------------------------------------------------------------
+
+PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
+get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR)
 
 # -- Project information -----------------------------------------------------
 
-project = "junifer"
-copyright = "2023, Authors of junifer"
-author = "Fede Raimondo"
+github_url = "https://github.com"
+github_repo_org = "juaml"
+github_repo_name = "junifer"
+github_repo_slug = f"{github_repo_org}/{github_repo_name}"
+github_repo_url = f"{github_url}/{github_repo_slug}"
+
+project = github_repo_name
+author = f"{project} Contributors"
+copyright = f"{datetime.date.today().year}, {author}"
+
+# The version along with dev tag
+release = get_scm_version(
+    version_scheme="guess-next-dev",
+    local_scheme="no-local-version",
+)
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # Built-in extensions:
     "sphinx.ext.autodoc",  # include documentation from docstrings
     "sphinx.ext.autosummary",  # generate autodoc summaries
     "sphinx.ext.doctest",  # test snippets in the documentation
+    "sphinx.ext.extlinks",  # markup to shorten external links
     "sphinx.ext.intersphinx",  # link to other projects` documentation
     "sphinx.ext.mathjax",  # math support for HTML outputs in Sphinx
+    # Third-party extensions:
     "sphinx_gallery.gen_gallery",  # HTML gallery of examples
     "numpydoc",  # support for NumPy style docstrings
-    "gh_substitutions",  # custom GitHub substitutions
     "sphinx_copybutton",  # copy button for code blocks
     "sphinxcontrib.mermaid",  # mermaid support
+    "sphinxcontrib.towncrier.ext",  # towncrier fragment support
 ]
 
 if use_multiversion:
@@ -88,11 +100,8 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-#
 html_theme = "furo"
-
+html_title = "junifer documentation"
 html_logo = "./images/junifer_logo.png"
 
 # These paths are either relative to html_static_path
@@ -146,6 +155,12 @@
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
 }
 
+# -- sphinx.ext.extlinks configuration ---------------------------------------
+
+extlinks = {
+    "gh": (f"{github_repo_url}/issues/%s", "#%s"),
+}
+
 # -- numpydoc configuration --------------------------------------------------
 
 numpydoc_show_class_members = False
@@ -197,3 +212,9 @@
 smv_tag_whitelist = r"^v\d+\.\d+.\d+$"
 smv_branch_whitelist = r"main"
 smv_released_pattern = r"^tags/v.*$"
+
+# -- sphinxcontrib-towncrier configuration -----------------------------------
+
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = PROJECT_ROOT_DIR

docs/whats_new.rst

@@ -6,6 +6,8 @@
 What's new
 ==========
 
+.. towncrier-draft-entries:: |release|
+
 .. towncrier release notes start
 
 Junifer 0.0.5 (2024-07-22)

pyproject.toml

@@ -85,6 +85,8 @@ docs = [
     "sphinx-copybutton>=0.5.1,<0.5.3",
     "towncrier>=23.10.0,<23.12.0",
     "sphinxcontrib-mermaid>=0.8.1,<0.10",
+    "sphinxcontrib-towncrier==0.4.0a0",
+    "setuptools-scm>=8",
 ]
 
 ################