[INFRA] Update sphinx conf for newer version, correct warnings (#69)

* Update sphinx conf for newer version, correct warnings

* Fix introduced flake8 errors

* Remove nistats intersphinx

* Patch to use older fmralign theme

.gitignore

@@ -58,6 +58,8 @@ coverage.xml
 .pytest_cache/
 
 # Sphinx documentation
+doc/_build/
+doc/auto_examples/
 source/_build/
 source/auto_examples/
 

doc/conf.py

@@ -11,14 +11,15 @@
 import os
 import sys
 
-import sphinx
+import fmralign
+
+current_version = fmralign.__version__
 
 # 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.insert(0, os.path.abspath("sphinxext"))
-import sphinx_gallery
 
 # We also add the directory just above to enable local imports of fmralign
 sys.path.insert(0, os.path.abspath(".."))
@@ -28,12 +29,7 @@
 
 # General information about the project.
 project = "fmralign"
-copyright = "The fmralign developers 2018-2019"
-author = "The fmralign developers"
-# The short X.Y version
-version = "0.0"
-# The full version, including alpha/beta/rc tags
-release = "0.0.1"
+copyright = "fmralign developers 2018-2023"
 
 
 # -- General configuration ---------------------------------------------------
@@ -80,7 +76,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -105,7 +101,7 @@
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
-html_style = "nature.css"
+# html_style = "nature.css"
 
 # 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
@@ -115,7 +111,6 @@
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ["themes"]
 
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = "fMRI alignment"
@@ -125,7 +120,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "logos/nilearn-logo.png"
+html_logo = ""
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -175,98 +170,38 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "fmraligndoc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # 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',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (
-        master_doc,
-        "fmralign.tex",
-        "fmralign Documentation",
-        "T. Bazeille, B. Thirion",
-        "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, "fmralign", "fmralign Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "fmralign",
-        "fmralign Documentation",
-        author,
-        "fmralign",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
-
+htmlhelp_basename = "PythonScientific"
 
 # -- Extension configuration -------------------------------------------------
 numpydoc_show_class_members = False
 
-_python_doc_base = "http://docs.python.org/3.7"
-"""
+_python_doc_base = "http://docs.python.org/3.9"
+
+# Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': (_python_doc_base, None),
-    'numpy': ('http://docs.scipy.org/doc/numpy', None),
-    'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
-    'matplotlib': ('http://matplotlib.org/', None),
-    'nipy': ('http://nipy.org/nibabel', None),
-    'nilearn': ('http://nilearn.github.io', None),
-    'nibabel': ('http://nipy.org/nibabel', None),
-    'sklearn': ('http://scikit-learn.org/stable', None),
-    'patsy': ('http://patsy.readthedocs.io/en/latest/', None),
-    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
+    "python": (_python_doc_base, None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://scipy.github.io/devdocs/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "nibabel": ("https://nipy.org/nibabel", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
+}
+
+extlinks = {
+    "sklearn": ("https://scikit-learn.org/stable/%s", None),
+    "inria": ("https://team.inria.fr/%s", None),
+    "nilearn-gh": ("https://github.com/nilearn/nilearn/%s", None),
+    "neurostars": ("https://neurostars.org/tag/nilearn/%s", None),
+    "nipy": ("https://nipy.org/%s", None),
 }
-"""
+
+# Check intersphinx reference targets exist
+nitpicky = True
+# Temporary solution to nilearn/nilearn#3800
+# See also scikit-learn/scikit-learn#26761
+nitpick_ignore = [
+    ("py:class", "pipeline.Pipeline"),
+    ("py:class", "utils.metadata_routing.MetadataRequest"),
+]

doc/functional_alignment/fmralign_pipeline.rst

@@ -1,10 +1,10 @@
 .. fmralign_pipeline:
 
-=======================================
+=============================
 Functional alignment pipeline
-=======================================
+=============================
 
-As seen in the :ref:`previous section <functional_alignment_intro.rst>`,
+As seen in the :ref:`previous section <introduction>`,
 functional alignment searches for a transform between images of two or several subjects in order to match voxels which have similar profile of activation.
 This section explains how this transform is found in fmralign to make the process easy, efficient and scalable.
 
@@ -17,7 +17,7 @@ We will just work here on a ROI.
     :depth: 1
 
 Local functional alignment
-==================================
+==========================
 
 .. figure:: ../images/alignment_pipeline.png
    :scale: 25
@@ -43,7 +43,7 @@ parcellation chosen can obviously have an impact. We recommend 'ward' to have sp
 
 
 Alignment methods on a region
-==================================
+=============================
 
 .. topic:: **Full code example on 2D simulated data**
 
@@ -62,7 +62,7 @@ We show below a 2D example, with 2 distributions: `X` in green, `Y` in red. Both
    :align: left
 
 Orthogonal alignment (Procrustes)
-----------------------------------
+---------------------------------
 The first idea proposed in Haxby, 2011 was to compute an orthogonal mixing
 matrix `R` and a scaling `sc` such that Frobenius norm :math:`||sc RX - Y||^2` is minimized.
 
@@ -73,7 +73,7 @@ matrix `R` and a scaling `sc` such that Frobenius norm :math:`||sc RX - Y||^2` i
    :align: left
 
 Ridge alignment
-----------------------------------
+---------------
 Another simple idea to regularize the transform `R` searched for is to penalize its L2 norm. This is a ridge regression, which means we search `R` such that Frobenius  norm :math:`|| XR - Y ||^2 + alpha * ||R||^2` is minimized with cross-validation.
 
 .. figure:: ../auto_examples/images/sphx_glr_plot_alignment_simulated_2D_data_005.png
@@ -84,7 +84,7 @@ Another simple idea to regularize the transform `R` searched for is to penalize
 
 
 Optimal Transport alignment
-----------------------------------
+---------------------------
 Finally this package comes with a new method that build on the Wasserstein distance which is well-suited for this problem. This is the framework of Optimal Transport that search to transport all signal from `X` to `Y`
 while minimizign the overall cost of this transport. `R` is here the optimal coupling between `X` and `Y` with entropic regularization.
 
@@ -96,7 +96,7 @@ while minimizign the overall cost of this transport. `R` is here the optimal cou
 
 
 Comparing those methods on a region of interest
-=================================================
+===============================================
 
 .. topic:: **Full code example**
 
@@ -107,7 +107,7 @@ Now let's compare the performance of these various methods on our simple example
 the prediction of left-out data for a new subject from another subjects data.
 
 Loading the data
-------------------------------
+----------------
 We begin with the retrieval of images from two `Individual Brain Charting <https://project.inria.fr/IBC/>`_ subjects :
 
 >>> from fmralign.fetch_example_data import fetch_ibc_subjects_contrasts
@@ -117,7 +117,7 @@ Here `files` is the list of paths for each subject and `df` is a pandas Datafram
 with metadata about each of them.
 
 Extract a mask for the visual cortex from Yeo Atlas
-----------------------------------------------------
+---------------------------------------------------
 
 >>> from nilearn import datasets, plotting
 >>> from nilearn.image import resample_to_img, load_img, new_img_like
@@ -146,7 +146,7 @@ Define a masker
 
 
 Prepare the data
--------------------
+----------------
 For each subject, for each task and conditions, our dataset contains two
 independent acquisitions, similar except for one acquisition parameter, the
 encoding phase used that was either Antero-Posterior (AP) or Postero-Anterior (PA).
@@ -172,7 +172,7 @@ The testing fold:
 >>> target_test = df[df.subject == 'sub-02'][df.acquisition == 'pa'].path.values
 
 Define the estimators, fit them and do a prediction
----------------------------------------------------------------------------
+---------------------------------------------------
 To proceed with alignment we use the class PairwiseAlignment with the masker we created before.
 
 First we choose a suitable number of regions such that each regions is approximately 200 voxels wide.

doc/functional_alignment/index.rst

@@ -16,5 +16,5 @@ functional characteristics across subjects or to improve `decoding <https://nile
 
 .. toctree::
 
-   functional_alignment_intro.rst
+   introduction.rst
    fmralign_pipeline.rst

doc/functional_alignment/functional_alignment_intro.rst → doc/functional_alignment/introduction.rst

@@ -1,8 +1,8 @@
 .. for doctests to run, we need to define variables that are define in
    the literal includes
     >>> # if need to do something
-..
-.. functional_alignment_intro:
+
+.. _introduction:
 
 =======================================
 An introduction to functional alignment
@@ -25,7 +25,7 @@ In this documentation we use a subset of `Individual Brain Charting dataset <htt
 
 
 Inter subject variability in fMRI
-==================================
+=================================
 In order to better understand brain function, many dataset acquire precise individual
 functional images. Some rely on task and contrasts with a semantic,
 (`Human Connectome Project <http://www.humanconnectomeproject.org/>`_ , `Individual Brain Charting <https://project.inria.fr/IBC/>`_),
@@ -85,7 +85,7 @@ which illustrate that functional signals are widely different between subject
 even in simple and narrow experimental settings.
 
 Functional alignment
-=====================
+====================
 
 The core idea of functional alignment is to handle this variablity by learning a transformation
 from one subject to another.
@@ -104,7 +104,7 @@ The say we have the 'AP' images in common for both subjects, we only have 'PA' i
 and we want to predict it for sub-02.
 
 Learning the transformation and predicting new data
-----------------------------------------------------
+---------------------------------------------------
 
 As we want to learn the transformation on 'AP' images, we should retrieve these images we left aside a moment ago :
 

doc/modules/generated/fmralign.alignment_methods.DiagonalAlignment.rst

@@ -1,4 +1,4 @@
-
+
 .. note::
 
    This page is a reference documentation. It only explains the class
@@ -12,7 +12,7 @@ fmralign.alignment_methods.DiagonalAlignment
 .. currentmodule:: fmralign.alignment_methods
 
 .. autoclass:: DiagonalAlignment
-   :inherited-members:
+   :no-inherited-members:
 
 
    .. automethod:: __init__

doc/modules/generated/fmralign.alignment_methods.Hungarian.rst

@@ -1,4 +1,4 @@
-
+
 .. note::
 
    This page is a reference documentation. It only explains the class
@@ -12,7 +12,7 @@ fmralign.alignment_methods.Hungarian
 .. currentmodule:: fmralign.alignment_methods
 
 .. autoclass:: Hungarian
-   :inherited-members:
+   :no-inherited-members:
 
 
    .. automethod:: __init__

doc/modules/generated/fmralign.alignment_methods.Identity.rst

@@ -1,4 +1,4 @@
-
+
 .. note::
 
    This page is a reference documentation. It only explains the class
@@ -12,7 +12,7 @@ fmralign.alignment_methods.Identity
 .. currentmodule:: fmralign.alignment_methods
 
 .. autoclass:: Identity
-   :inherited-members:
+   :no-inherited-members:
 
 
    .. automethod:: __init__