Fixed documentation build error and warnings

[ZviBaratz]

This resolves #1162, however, there are still some documents not included in any toctree, which raises warnings.

.../nibabel/doc/source/devel/bv_formats.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/devel/data_pkg_discuss.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/devel/data_pkg_uses.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/devel/image_design.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/devel/scaling.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/installing_data.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/notebooks/index.rst: WARNING: document isn't included in any toctree
.../nibabel/doc/source/old/ioimplementation.rst: WARNING: document isn't included in any toctree

Should any of these be removed? Or included in any existing / new section?

[codecov]

Codecov Report

Base: 92.38% // Head: 92.38% // No change to project coverage 👍

Coverage data is based on head (e86addb) compared to base (0a6e73e).
Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1163   +/-   ##
=======================================
  Coverage   92.38%   92.38%           
=======================================
  Files          98       98           
  Lines       12264    12264           
  Branches     2520     2520           
=======================================
  Hits        11330    11330           
  Misses        613      613           
  Partials      321      321           

Impacted Files	Coverage Δ
nibabel/batteryrunners.py	95.83% <ø> (ø)
nibabel/ecat.py	88.18% <ø> (ø)
nibabel/gifti/__init__.py	100.00% <ø> (ø)
nibabel/processing.py	100.00% <ø> (ø)
nibabel/quaternions.py	99.01% <ø> (ø)
nibabel/spatialimages.py	96.29% <ø> (ø)
nibabel/tmpdirs.py	92.10% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[ZviBaratz]

@effigies there are also suddenly doctest failures that weren't there before. Any idea what happened?

[effigies]

I think there's something that happened with upgrading sphinx that changed the behavior of autosummary. I believe that the :toctree: reference had something to do with it, but I haven't been able to figure it out yet.

[ZviBaratz]

Are these really meant to be doctests? If so, shouldn't we either include the imports or add doctest_global_setup to conf.py?

[effigies]

Yes, the idea is that all of the example code should run, so we know the documentation is valid. Could be that there was an implicit context in earlier sphinx that now needs to be managed directly.

[ZviBaratz]

No problem. Do you think it would be better to import all the relevant objects in the global context or per test? E.g., in quaternions.py:

>>> import numpy as np
>>> from nibabel.quaternions import quat2mat  # Added
>>> q = [0, 1, 0, 0] # 180 degree rotation around axis 0
>>> M = quat2mat(q) # from this module
>>> vec = np.array([1, 2, 3]).reshape((3,1)) # column vector
>>> tvec = np.dot(M, vec)

or add all the required imports in doctest_global_setup?

I'm leaning towards the first option. WDYT?

[effigies]

Wait, so doctests in the current file don't have access to the variables in that file? That seems like a regression in sphinx, or possibly some option that was switched from defaulting true to false.

[effigies]

Seems this is a known issue: sphinx-doc/sphinx#6590

[ZviBaratz]

From what I gather, it doesn't seem like there's an easy workaround, nor that this will be resolved any time soon. Any suggestions?

[effigies]

Let's just import the current module.

[ZviBaratz]

There's a ModuleNotFoundError for pytest. I tried adding it to the workflow's dependencies installation step, but strangely it's still there. Will have more time to try to figure it out during the weekend. Meanwhile, any ideas would be very welcome.

[effigies]

@matthew-brett Is the make api-stamp replaceable with some invocation of autosummary? I don't fully understand everything that's going on here.

[effigies]

I'm going to merge this. We can do additional fixups if you spot anything...