junifer 0.0.8.dev249__tar.gz → 0.0.8.dev253__tar.gz

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/.github/workflows/docs-preview.yml

@@ -22,9 +22,11 @@ jobs:
       contents: write
     steps:
     - name: Check ANTs
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       run: |
         echo "Using ANTs : $(antsRegistration --version)"
     - name: Check tooling
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       run: |
         which make git-annex jq
         ls -d "$HOME"/junifer_data/v7
@@ -34,21 +36,26 @@ jobs:
         fetch-depth: 0
         submodules: true
     - name: Set up Python
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       uses: actions/setup-python@v7
       with:
         python-version: "3.12"
     - name: Set up uv
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       uses: astral-sh/setup-uv@v10.2.0
     - name: Install Python dependencies
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       run: |
-        uv pip install --system -e ".[docs,neurokit2]"
+        uv sync --locked --extra docs
     - name: Configure Git for DataLad
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       run: |
         git config --global user.email "junifer-runner@github.com"
         git config --global user.name "GitHub Runner"
     - name: Test build docs
+      if: github.event.action != 'closed' # The build is not needed when the preview is removed
       run: |
-        BUILDDIR=_build/main make -C docs/ local
+        BUILDDIR=_build/main uv run make -C docs/ local
     - name: Deploy preview
       if: github.event_name == 'pull_request'
       uses: rossjrw/pr-preview-action@v1

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/.github/workflows/docs.yml

@@ -35,8 +35,7 @@ jobs:
       uses: astral-sh/setup-uv@v10.2.0
     - name: Install Python dependencies
       run: |
-        uv pip install --system -e ".[docs,neurokit2]"
-        uv pip install --system git+https://github.com/dls-controls/sphinx-multiversion@only-arg
+        uv sync --locked --extra docs
     - name: Configure Git for DataLad
       run: |
         git config --global user.email "junifer-runner@github.com"
@@ -49,13 +48,13 @@ jobs:
           ref: gh-pages
           path: docs/_build
     - name: Build docs
-      # Use the args we normally pass to sphinx-build, but run sphinx-multiversion
+      # Build all the versions with sphinx-polyversion; the versions already
+      # in gh-pages are kept and only the missing ones are built
       # https://github.com/actions/checkout/issues/1169#issuecomment-2291682583
       run: |
         git config --global --add safe.directory $(pwd)
-        make -C docs/ html
+        uv run make -C docs/ html
         touch docs/_build/.nojekyll
-        cp docs/redirect.html docs/_build/index.html
     - name: Publish docs to gh-pages
       uses: peaceiris/actions-gh-pages@v4
       with:

{junifer-0.0.8.dev249/junifer.egg-info → junifer-0.0.8.dev253}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: junifer
-Version: 0.0.8.dev249
+Version: 0.0.8.dev253
 Summary: JUelich NeuroImaging FEature extractoR
 Author-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
 Maintainer-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
@@ -63,20 +63,24 @@ Requires-Dist: tox; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: towncrier; extra == "dev"
+Provides-Extra: sphinx
+Requires-Dist: seaborn<0.14.0,>=0.13.0; extra == "sphinx"
+Requires-Dist: sphinx<8.4.0,>=7.3.0; extra == "sphinx"
+Requires-Dist: sphinx-gallery<0.20.0,>=0.17.0; extra == "sphinx"
+Requires-Dist: furo<2025.10.0,>=2024.4.27; extra == "sphinx"
+Requires-Dist: numpydoc<=1.9.0,>=1.6.0; extra == "sphinx"
+Requires-Dist: julearn==0.3.5; extra == "sphinx"
+Requires-Dist: sphinx-copybutton<0.5.3,>=0.5.1; extra == "sphinx"
+Requires-Dist: towncrier<=25.8.0,>=24.7.0; extra == "sphinx"
+Requires-Dist: sphinxcontrib-mermaid<=1.0.0,>=0.8.1; extra == "sphinx"
+Requires-Dist: sphinxcontrib-towncrier==0.5.0a0; extra == "sphinx"
+Requires-Dist: setuptools-scm>=8; extra == "sphinx"
+Requires-Dist: autodoc_pydantic>=2.0.0; extra == "sphinx"
+Requires-Dist: enum-tools[sphinx]<0.14.0,>=0.13.0; extra == "sphinx"
+Requires-Dist: sphinx-polyversion>=2.0.0; extra == "sphinx"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "sphinx"
 Provides-Extra: docs
-Requires-Dist: seaborn<0.14.0,>=0.13.0; extra == "docs"
-Requires-Dist: sphinx<8.4.0,>=7.3.0; extra == "docs"
-Requires-Dist: sphinx-gallery<0.20.0,>=0.17.0; extra == "docs"
-Requires-Dist: furo<2025.10.0,>=2024.4.27; extra == "docs"
-Requires-Dist: numpydoc<=1.9.0,>=1.6.0; extra == "docs"
-Requires-Dist: julearn==0.3.5; extra == "docs"
-Requires-Dist: sphinx-copybutton<0.5.3,>=0.5.1; extra == "docs"
-Requires-Dist: towncrier<=25.8.0,>=24.7.0; extra == "docs"
-Requires-Dist: sphinxcontrib-mermaid<=1.0.0,>=0.8.1; extra == "docs"
-Requires-Dist: sphinxcontrib-towncrier==0.5.0a0; extra == "docs"
-Requires-Dist: setuptools-scm>=8; extra == "docs"
-Requires-Dist: autodoc_pydantic>=2.0.0; extra == "docs"
-Requires-Dist: enum-tools[sphinx]<0.14.0,>=0.13.0; extra == "docs"
+Requires-Dist: junifer[all,sphinx]; extra == "docs"
 Dynamic: license-file
 
 ![Junifer logo](docs/images/junifer_logo.png "junifer logo")

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/docs/Makefile

@@ -4,32 +4,38 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?="-W" "-E"
-SPHINXBUILD   ?= sphinx-multiversion
+SPHINXBUILD   ?= sphinx-build
+POLYBUILD     ?= sphinx-polyversion
 SOURCEDIR     = .
+# Output of the local (single version) build, relative to docs/
 BUILDDIR      ?= _build
+# Output of the multi-version build, relative to the repository root
+POLYOUTDIR    ?= docs/_build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) --help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile clean local news _build_local _html
+.PHONY: help Makefile clean local news _build_local html _html
 
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf auto_examples/
 	rm -rf api/generated/
 
+# Build the docs of the working tree only
 local:
 	make _build_local; STATUS=$$?; exit $$STATUS
 
 _build_local:
-	sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Build the docs of all the versions with sphinx-polyversion
 html:
 	make _html; STATUS=$$?; exit $$STATUS
 
 _html:
-	$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	$(POLYBUILD) ./poly.py -vv -o OUTPUT_DIR="$(POLYOUTDIR)" -o SOURCE_DIR="./"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

junifer-0.0.8.dev253/docs/_static/css/version_selector.css

@@ -0,0 +1,126 @@
+/* Furo-native version selector styles.
+   Uses furo CSS variables for full light/dark mode compatibility. */
+
+/* ── Sidebar version selector ────────────────────────────────────────────── */
+
+#version-selector {
+    border-top: 1px solid var(--color-sidebar-search-border);
+    padding-top: calc(var(--sidebar-item-spacing-vertical) / 2);
+}
+
+/* Remove default browser <details> marker */
+.version-details > summary {
+    list-style: none;
+}
+.version-details > summary::-webkit-details-marker {
+    display: none;
+}
+
+/* Summary row: looks like a furo sidebar caption */
+.version-summary {
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 0.4em;
+    padding: var(--sidebar-item-spacing-vertical)
+        var(--sidebar-item-spacing-horizontal);
+    font-size: var(--font-size--small--2);
+    font-weight: bold;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    color: var(--color-sidebar-caption-text);
+    user-select: none;
+}
+
+.version-summary:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+/* Chevron: points right when closed, down when open */
+.version-summary::after {
+    content: "▶";
+    font-size: 0.6em;
+    margin-left: auto;
+    transition: transform 0.15s ease;
+    color: var(--color-sidebar-caption-text);
+}
+
+.version-details[open] > .version-summary::after {
+    transform: rotate(90deg);
+}
+
+/* Colored status dot */
+.version-status-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    display: inline-block;
+    flex-shrink: 0;
+}
+
+.version-status-dot--latest { background-color: #28a745; }
+.version-status-dot--old    { background-color: #dc3545; }
+.version-status-dot--dev    { background-color: #e67e00; }
+
+/* Version list */
+.version-details ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.version-details .toctree-l1 > a {
+    display: block;
+    padding: var(--sidebar-item-spacing-vertical)
+        var(--sidebar-item-spacing-horizontal);
+    color: var(--color-sidebar-link-text);
+    font-size: var(--sidebar-item-font-size);
+    text-decoration: none;
+}
+
+.version-details .toctree-l1 > a:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+    color: var(--color-sidebar-link-text--top-level);
+}
+
+.version-details .toctree-l1.current > a {
+    background-color: var(--color-sidebar-item-background--current, transparent);
+    color: var(--color-sidebar-link-text--top-level);
+    font-weight: bold;
+}
+
+.version-details .toctree-l1 > a em {
+    font-size: 0.85em;
+    opacity: 0.75;
+}
+
+/* ── Version banner (toc-drawer / right sidebar) ─────────────────────────── */
+
+.version-banner {
+    padding: 0.6rem 0.75rem;
+    margin: 0.75rem 0.5rem 0;
+    border-radius: 0.2rem;
+    border-left: 3px solid;
+    font-size: var(--font-size--small--2);
+    line-height: 1.4;
+}
+
+.version-banner a {
+    font-weight: bold;
+    color: inherit;
+}
+
+.version-banner--latest {
+    background-color: rgba(40, 167, 69, 0.12);
+    border-left-color: #28a745;
+}
+
+.version-banner--old {
+    background-color: rgba(220, 53, 69, 0.12);
+    border-left-color: #dc3545;
+}
+
+.version-banner--dev {
+    background-color: rgba(230, 126, 0, 0.12);
+    border-left-color: #e67e00;
+}

junifer-0.0.8.dev253/docs/_templates/versions.html

@@ -0,0 +1,11 @@
+{# Furo-native version selector.
+   This placeholder is rendered by Sphinx at build time.
+   poly.py replaces it with the full multi-version list when patching. #}
+<div id="version-selector" class="sidebar-tree version-selector">
+  <details class="version-details" open>
+    <summary class="version-summary">
+      <span class="version-status-dot version-status-dot--latest"></span>
+      <span class="caption-text">Version</span>
+    </summary>
+  </details>
+</div>

junifer-0.0.8.dev253/docs/changes/newsfragments/513.doc

@@ -0,0 +1 @@
+Build the documentation of all the released versions with ``sphinx-polyversion`` instead of ``sphinx-multiversion``, using a ``uv`` environment per version, and add a version selector and a banner showing whether the latest, an old or the development version is being viewed by `Fede Raimondo`_

junifer-0.0.8.dev253/docs/changes/newsfragments/513.misc

@@ -0,0 +1 @@
+Add the ``sphinx`` optional dependencies with the tools to build the documentation, make ``docs`` include everything needed to build it, and skip building the PR preview of the documentation when the PR is closed by `Fede Raimondo`_

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/docs/conf.py

@@ -7,26 +7,15 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import datetime
-from functools import partial
+import os
 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
-
-
 # -- Path setup --------------------------------------------------------------
 
 PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
-get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR)
 
 # -- Project information -----------------------------------------------------
 
@@ -40,12 +29,6 @@ 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
@@ -69,9 +52,6 @@ extensions = [
     "enum_tools.autoenum",  # enum support
 ]
 
-if use_multiversion:
-    extensions.append("sphinx_multiversion")
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [
     "_templates",
@@ -105,6 +85,10 @@ nitpick_ignore_regex = [
     ("py:obj", "them"),  # ignore them
     ("py:class", "junifer.utils.helpers.ensure_list"),  # ignore ensure_list
     ("py:class", "junifer.utils.helpers.ensure_list_or_none"),  # ignore ensure_list_or_none
+    # Unresolved names in source annotations, e.g. ``types`` of
+    # PatternDataladDataGrabber when building with sphinx-polyversion
+    ("py:class", "BeforeValidator"),
+    ("py:class", "ensure_list"),
     ("py:class", "PydanticUndefined"),  # ignore PydanticUndefined
     ("py:class", "FieldInfo"),  # ignore FieldInfo
     ("py:class", "NoneType"),  # ignore NoneType
@@ -120,6 +104,7 @@ html_logo = "./images/junifer_logo.png"
 # or fully qualified paths (eg. https://...)
 html_css_files = [
     "css/custom.css",
+    "css/version_selector.css",
 ]
 
 html_js_files = [
@@ -177,6 +162,43 @@ def _load_junifer() -> None:
 
 _load_junifer()
 
+# -- Version information -----------------------------------------------------
+
+# sphinx-polyversion is only imported (and needed) for multi-version builds;
+# local builds get the version from setuptools-scm.
+if os.getenv("POLYVERSION_DATA") is None:
+    # If POLYVERSION_DATA is not set, we are likely building the docs locally.
+    # In this case, we can use setuptools_scm to get the version information.
+    release = get_version(
+        root=PROJECT_ROOT_DIR,
+        version_scheme="guess-next-dev",
+        local_scheme="no-local-version",
+    )
+else:
+    # Only needed (and installed) when building with sphinx-polyversion
+    from sphinx_polyversion.api import load
+    from sphinx_polyversion.git import GitRefType
+
+    load(globals())
+    # This adds the following to the global scope
+    # html_context = {
+    #     "revisions": [GitRef('main', ...), GitRef('v6.8.9', ...), ...],
+    #     "current": GitRef('v1.4.6', ...),
+    # }
+
+    # process the loaded version information as you wish
+    html_context = globals().get("html_context", {})
+
+    if (
+        html_context["current"].type_ == GitRefType.BRANCH
+        and html_context["current"].name == "main"
+    ):
+        release = os.getenv("SETUPTOOLS_SCM_PRETEND_VERSION_FOR_JUNIFER")
+    else:
+        release = html_context["current"].name
+
+version = release
+
 # -- sphinx.ext.autosummary configuration ------------------------------------
 
 autosummary_generate = True
@@ -248,13 +270,6 @@ sphinx_gallery_conf = {
     "backreferences_dir": "generated",
 }
 
-# -- sphinx-multiversion configuration ---------------------------------------
-
-smv_rebuild_tags = False
-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"

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/docs/contribution.rst

@@ -147,23 +147,34 @@ Adding and building documentation
 
 Building the documentation requires some extra packages and can be installed by
 
+.. code-block:: bash
+
+    uv sync --extra docs
+
+or, with ``pip``:
+
 .. code-block:: bash
 
     pip install -e ".[docs]"
 
-To build the docs
+To build the docs of your working copy
 
 .. code-block:: bash
 
     cd docs
     make local
 
-To view the documentation, open ``docs/_build/html/index.html``.
+To view the documentation, open ``docs/_build/index.html``.
 
 In case you remove some files or change their filenames, you can run into
 errors when using ``make local``. In this situation you can use ``make clean``
 to clean up the already build files and then re-run ``make local``.
 
+The published documentation contains all the released versions and is built
+with `sphinx-polyversion`_ using ``make html``. It builds each version in its
+own environment (defined in ``docs/poly.py``) and only builds the versions
+that are not already present in ``docs/_build``.
+
 Also, we follow British English for the documentation.
 
 

{junifer-0.0.8.dev249 → junifer-0.0.8.dev253}/docs/links.inc

@@ -47,3 +47,4 @@
 .. _`HTCondor`: https://research.cs.wisc.edu/htcondor/
 .. _`SLURM`: https://slurm.schedmd.com
 .. _`GNU Parallel`: https://www.gnu.org/software/parallel/
+.. _`sphinx-polyversion`: https://real-yfprojects.github.io/sphinx-polyversion