Merge pull request #1163 from ZviBaratz/docs

Fixed documentation build error and warnings

Author: effigies

.github/workflows/misc.yml

@@ -24,7 +24,7 @@ jobs:
       matrix:
         python-version: ["3.10"]
         install: ['pip']
-        check: ['style', 'doc']
+        check: ['style', 'doctest']
         pip-flags: ['']
         depends: ['REQUIREMENTS']
     env:

doc-requirements.txt

@@ -1,6 +1,7 @@
-# Requirements for building docs
+# Auto-generated by tools/update_requirements.py
 -r requirements.txt
-sphinx<3
+matplotlib >= 1.5.3
 numpydoc
+sphinx ~= 5.3
 texext
-matplotlib >=1.3.1
+tomli; python_version < "3.11"

doc/source/conf.py

@@ -23,7 +23,10 @@
 from pathlib import Path
 from runpy import run_path
 
-import toml
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
 
 # Check for external Sphinx extensions we depend on
 try:
@@ -52,14 +55,15 @@
     fobj.write(rel['long_description'])
 
 # Load metadata from setup.cfg
-pyproject_dict = toml.load(Path("../../pyproject.toml"))
-metadata = pyproject_dict["project"]
+with open(Path("../../pyproject.toml"), 'rb') as fobj:
+    pyproject = tomllib.load(fobj)
+authors = pyproject["project"]["authors"][0]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
-              #'sphinx.ext.intersphinx',
+              'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.mathjax',
               'sphinx.ext.inheritance_diagram',
@@ -69,9 +73,10 @@
               'matplotlib.sphinxext.plot_directive',
               ]
 
-# the following doesn't work with sphinx < 1.0, but will make a separate
-# sphinx-autogen run obsolete in the future
-#autosummary_generate = True
+# Autosummary always wants to use a `generated/` directory.
+# We generate with `make api-stamp`
+# This could change in the future
+autosummary_generate = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -87,9 +92,7 @@
 
 # General information about the project.
 project = u'NiBabel'
-author_name = metadata["authors"][0]["name"]
-author_email = metadata["authors"][0]["email"]
-copyright = f"2006-2022, {author_name} <{author_email}>"
+copyright = f"2006-2022, {authors['name']} <{authors['email']}>"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -269,7 +272,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}
 
 # Config of plot_directive
 plot_include_source = True

doc/source/devel/biaps/biap_0003.rst

@@ -199,8 +199,8 @@ The base level header will usually also have image metadata fields giving
 information about the whole image. A field is an "image metadata field" if it
 is defined at the top level of the header.  For example::
 
->>> hdr = dict(nipy_header_version='1.0',
-...            Manufacturer="SIEMENS")
+      >>> hdr = dict(nipy_header_version='1.0',
+      ...            Manufacturer="SIEMENS")
 
 All image metadata fields are optional.
 
@@ -635,7 +635,7 @@ Use case
 ^^^^^^^^
 
 When doing motion correction on a 4D image, we calculate the required affine
-transformation from |--| say |--| the second image to the first image; the
+transformation from, say, the second image to the first image; the
 third image to the first image; etc. If there are N volumes in the 4D image,
 we would need to store N-1 affine transformations.  If we have registered to
 the mean volume of the volume series instead of one of the volumes in the

doc/source/devel/biaps/biap_0004.rst

@@ -221,6 +221,7 @@ Improving access to varying meta data through the Nifti
 
 Currently, when accessing varying meta data through the `get_meta` method 
 you can only get one value at a time::
+
     >>> echo_times = [nii.get_meta('EchoTime', (0, 0, 0, idx)) 
                       for idx in xrange(data.shape[-1])]
 

doc/source/devel/biaps/biap_0006.rst

@@ -193,7 +193,7 @@ In NIfTI:
 
 We saw above that the MGH format refers to a volume (in our sense) as a
 *frame*.  ECAT has the same usage - a frame is a 3D volume. The fmristat
-software uses frame in the same sense |--| e.g. `line 32 of example.m
+software uses frame in the same sense, e.g., `line 32 of example.m
 <https://github.com/matthew-brett/fmristat/blob/master/fmristat/example.m#L32>`_.
 
 Unfortunately DICOM appears to use "frame" to mean a 2D slice.  For example,

doc/source/devel/devdiscuss.rst

@@ -22,3 +22,7 @@ progress.
     spm_use
     modified_images
     data_pkg_design
+    data_pkg_discuss
+    data_pkg_uses
+    scaling
+    bv_formats

doc/source/devel/image_design.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ########################
 The nibabel image object
 ########################

doc/source/installing_data.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _installing-data:
 
 Installing data packages

doc/source/old/ioimplementation.rst

@@ -1,5 +1,7 @@
 .. -*- mode: rst -*-
 
+:orphan:
+
 ##################################################
 Relationship between images and io implementations
 ##################################################