From 9edac2f538ddd90c7624285accad01f25d6a6d6a Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Tue, 6 Aug 2024 07:14:02 +0200 Subject: [PATCH 1/9] docs: add sphinxcontrib-towncrier --- docs/Makefile | 18 ++++-------------- docs/conf.py | 7 +++++++ docs/whats_new.rst | 2 ++ pyproject.toml | 1 + 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 6bdee39ec..db2d120a1 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/conf.py b/docs/conf.py index bd22517c9..3d89de1c9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,7 @@ extensions = [ "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: @@ -197,3 +198,9 @@ 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" +towncrier_draft_include_empty = True +towncrier_draft_working_directory = curdir.parent diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 3c4350d15..4c7ebeee0 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -6,6 +6,8 @@ What's new ========== +.. towncrier-draft-entries:: + .. towncrier release notes start Junifer 0.0.5 (2024-07-22) diff --git a/pyproject.toml b/pyproject.toml index e9389fd0a..dd52013e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,6 +85,7 @@ 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", ] ################ -- 2.52.0 From e450718d93c5915d32a1f6f5cece231af70ff86e Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Wed, 7 Aug 2024 07:00:06 +0200 Subject: [PATCH 2/9] docs: improve path setup and project information in conf.py --- docs/conf.py | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3d89de1c9..cadc9de42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,17 +6,7 @@ # 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 pathlib import Path @@ -28,14 +18,22 @@ try: except ImportError: pass -curdir = Path(__file__).parent -sys.path.append((curdir / "sphinxext").as_posix()) + +# -- Path setup -------------------------------------------------------------- + +PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() # -- 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}" # -- General configuration --------------------------------------------------- @@ -203,4 +201,4 @@ smv_released_pattern = r"^tags/v.*$" towncrier_draft_autoversion_mode = "draft" towncrier_draft_include_empty = True -towncrier_draft_working_directory = curdir.parent +towncrier_draft_working_directory = PROJECT_ROOT_DIR -- 2.52.0 From 62752465066574569808835f7f4f3086c10a879c Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Wed, 7 Aug 2024 07:03:03 +0200 Subject: [PATCH 3/9] docs: use setuptools_scm to fetch version information in conf.py --- docs/conf.py | 11 +++++++++++ docs/whats_new.rst | 2 +- pyproject.toml | 1 + 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index cadc9de42..56fe664f5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,8 +7,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html 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 @@ -22,6 +25,7 @@ except ImportError: # -- Path setup -------------------------------------------------------------- PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve() +get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR) # -- Project information ----------------------------------------------------- @@ -35,6 +39,12 @@ 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 @@ -92,6 +102,7 @@ nitpick_ignore_regex = [ # html_theme = "furo" +html_title = "junifer documentation" html_logo = "./images/junifer_logo.png" # These paths are either relative to html_static_path diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 4c7ebeee0..b883a9cfa 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -6,7 +6,7 @@ What's new ========== -.. towncrier-draft-entries:: +.. towncrier-draft-entries:: |release| .. towncrier release notes start diff --git a/pyproject.toml b/pyproject.toml index dd52013e2..39ef99b4d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,6 +86,7 @@ docs = [ "towncrier>=23.10.0,<23.12.0", "sphinxcontrib-mermaid>=0.8.1,<0.10", "sphinxcontrib-towncrier==0.4.0a0", + "setuptools-scm>=8", ] ################ -- 2.52.0 From 1f0160d7360c2d64219a5477d263b4e1eefacbc7 Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Wed, 7 Aug 2024 07:04:07 +0200 Subject: [PATCH 4/9] docs: replace gh_substitutions with sphinx.ext.extlinks --- docs/conf.py | 8 +++++++- docs/sphinxext/gh_substitutions.py | 31 ------------------------------ 2 files changed, 7 insertions(+), 32 deletions(-) delete mode 100644 docs/sphinxext/gh_substitutions.py diff --git a/docs/conf.py b/docs/conf.py index 56fe664f5..7fb63382f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,11 +54,11 @@ 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 "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 @@ -156,6 +156,12 @@ intersphinx_mapping = { "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 diff --git a/docs/sphinxext/gh_substitutions.py b/docs/sphinxext/gh_substitutions.py deleted file mode 100644 index a3132d391..000000000 --- a/docs/sphinxext/gh_substitutions.py +++ /dev/null @@ -1,31 +0,0 @@ -"""Provide GitHub substitutions in Sphinx.""" - -from docutils.nodes import reference -from docutils.parsers.rst.roles import set_classes - - -# Taken from MNE-Python -# adapted from -# https://doughellmann.com/blog/2010/05/09/defining-custom-roles-in-sphinx/ - - -def gh_role(name, rawtext, text, lineno, inliner, options={}, content=[]): - """Link to a GitHub issue.""" - try: - # issue/PR mode (issues/PR-num will redirect to pull/PR-num) - int(text) - except ValueError: - # direct link mode - slug = text - else: - slug = "issues/" + text - text = "#" + text - ref = "https://github.com/juaml/junifer/" + slug - set_classes(options) - node = reference(rawtext, text, refuri=ref, **options) - return [node], [] - - -def setup(app): - app.add_role("gh", gh_role) - return -- 2.52.0 From 587bb59143d547a3b420314a650af956e26776da Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Wed, 7 Aug 2024 07:05:49 +0200 Subject: [PATCH 5/9] docs: improve commentary in conf.py --- docs/conf.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7fb63382f..47de3bf8a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,12 +51,14 @@ release = get_scm_version( # 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 "sphinx_copybutton", # copy button for code blocks @@ -97,9 +99,6 @@ nitpick_ignore_regex = [ # -- 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" -- 2.52.0 From 763e0a20df2f26f5b10544c3b9d3be3d9f1fa1df Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Wed, 7 Aug 2024 07:06:04 +0200 Subject: [PATCH 6/9] docs: whitespace management in conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 47de3bf8a..6765d35e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,6 +17,7 @@ from setuptools_scm import get_version use_multiversion = False try: import sphinx_multiversion # noqa: F401 + use_multiversion = True except ImportError: pass @@ -100,7 +101,6 @@ nitpick_ignore_regex = [ # -- Options for HTML output ------------------------------------------------- html_theme = "furo" - html_title = "junifer documentation" html_logo = "./images/junifer_logo.png" -- 2.52.0 From ea9bb4a532230053dbbd33022373ba88e7b2fd56 Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Thu, 22 Aug 2024 09:12:21 +0200 Subject: [PATCH 7/9] chore: improve FSL installation in ci.yml --- .github/workflows/ci.yml | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 559eed784..7607d2c57 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -93,16 +93,10 @@ 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/ + curl -fsSL https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py | python - -d /opt/fsl/ --skip_registration + FSLDIR="/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 + echo "/opt/fsl/bin" >> $GITHUB_PATH if: matrix.python-version == 3.11 # Bypass FSL installation failure continue-on-error: true -- 2.52.0 From d67c55ba6f701f5ae259f3776a6d9d9aabf16ba3 Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Thu, 22 Aug 2024 10:50:25 +0200 Subject: [PATCH 8/9] chore: fix FSL env vars in ci.yml --- .github/workflows/ci.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7607d2c57..228f05f37 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -94,8 +94,9 @@ jobs: - name: Install FSL run: | curl -fsSL https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py | python - -d /opt/fsl/ --skip_registration - FSLDIR="/opt/fsl" - FSLOUTPUTTYPE="NIFTI_GZ" + 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 -- 2.52.0 From d58754aa286e2c2398cc6181b5499b7c54d1fb99 Mon Sep 17 00:00:00 2001 From: Synchon Mandal Date: Tue, 27 Aug 2024 11:43:02 +0200 Subject: [PATCH 9/9] chore: add changelog 358.doc --- docs/changes/newsfragments/358.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/changes/newsfragments/358.doc diff --git a/docs/changes/newsfragments/358.doc b/docs/changes/newsfragments/358.doc new file mode 100644 index 000000000..928fde917 --- /dev/null +++ b/docs/changes/newsfragments/358.doc @@ -0,0 +1 @@ +Improve Sphinx configuration and extensions by `Synchon Mandal`_ -- 2.52.0