diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 559eed784..228f05f37 100644 --- a/.github/workflows/ci.yml +++ b/.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 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/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`_ diff --git a/docs/conf.py b/docs/conf.py index bd22517c9..6765d35e1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,36 +6,45 @@ # 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 --------------------------------------------------- @@ -43,16 +52,19 @@ author = "Fede Raimondo" # 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 @@ 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" html_logo = "./images/junifer_logo.png" # These paths are either relative to html_static_path @@ -146,6 +155,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 @@ -197,3 +212,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 = PROJECT_ROOT_DIR 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 diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 3c4350d15..b883a9cfa 100644 --- a/docs/whats_new.rst +++ b/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) diff --git a/pyproject.toml b/pyproject.toml index e9389fd0a..39ef99b4d 100644 --- a/pyproject.toml +++ b/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", ] ################