Cannot build docs immediately upon download due to distutil error

đź’¬ Support & Discussions
1

Environment details
MNE version: 0.24.1, main branch, SHA f0611b
operating system: e.g. macOS 10.15.7

Problem
After working through “Creating the virtual environment” of the Contributing Guide, I jumped to “Building the Documentation” to see if I had everything working, and to propose a minor tweak to the docs. Unfortunately, I never got the docs to build. See error below.

I see here that we fail on warnings. In this case I’m failing on a distutils warning. I was not able to fully follow, but perhaps it’s related to this github issue?

Terminal output

(mnedev) stephenzerfas@nfml-vbalcomGMH doc % make html_dev-noplot
BUILD_DEV_HTML=1 sphinx-build -D plot_gallery=0 -b html -d _build/doctrees  -nWT --keep-going . _build/html
Running Sphinx v4.4.0
Using pyvistaqt 3d backend.

making output directory... done
Building documentation for MNE 1.0.dev0 (/Users/stephenzerfas/src/mne-python/mne/__init__.py)
checking bibtex cache... out of date
parsing bibtex file /Users/stephenzerfas/src/mne-python/doc/references.bib... parsed 196 entries
[autosummary] generating autosummary for: bibliography.rst, cited.rst, connectivity.rst, covariance.rst, creating_from_arrays.rst, datasets.rst, decoding.rst, events.rst, export.rst, file_io.rst, ..., reading_raw_data.rst, realtime.rst, report.rst, sensor_space.rst, simulation.rst, source_space.rst, statistics.rst, time_frequency.rst, visualization.rst, whats_new.rst
[autosummary] generating autosummary for: /Users/stephenzerfas/src/mne-python/doc/generated/mne.AcqParserFIF.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.Annotations.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.BaseEpochs.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.BiHemiLabel.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.Covariance.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.Dipole.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.DipoleFixed.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.Epochs.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.EpochsArray.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.Evoked.rst, ..., /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_events.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_evokeds.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_forward_solution.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_head_bem.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_label.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_labels_to_annot.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_proj.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_source_spaces.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_surface.rst, /Users/stephenzerfas/src/mne-python/doc/generated/mne.write_trans.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://numpy.org/devdocs/objects.inv...
loading intersphinx inventory from https://scipy.github.io/devdocs/objects.inv...
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
loading intersphinx inventory from https://scikit-learn.org/stable/objects.inv...
loading intersphinx inventory from https://numba.pydata.org/numba-doc/latest/objects.inv...
loading intersphinx inventory from https://joblib.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://nipy.org/nibabel/objects.inv...
loading intersphinx inventory from http://nilearn.github.io/objects.inv...
loading intersphinx inventory from https://nipy.org/nitime/objects.inv...
loading intersphinx inventory from https://pysurfer.github.io/objects.inv...
loading intersphinx inventory from https://mne.tools/mne-bids/stable/objects.inv...
loading intersphinx inventory from https://mne.tools/mne-connectivity/stable/objects.inv...
loading intersphinx inventory from https://pandas.pydata.org/pandas-docs/stable/objects.inv...
loading intersphinx inventory from https://seaborn.pydata.org/objects.inv...
loading intersphinx inventory from https://www.statsmodels.org/dev/objects.inv...
loading intersphinx inventory from https://patsy.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.pyvista.org/objects.inv...
loading intersphinx inventory from https://imageio.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://mne.tools/mne-realtime/objects.inv...
loading intersphinx inventory from https://pierreablin.github.io/picard/objects.inv...
loading intersphinx inventory from https://qdarkstylesheet.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://eeglabio.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://dipy.org/documentation/latest/objects.inv/...
loading intersphinx inventory from https://www.fatiando.org/pooch/latest/objects.inv...
intersphinx inventory has moved: https://dipy.org/documentation/latest/objects.inv/ -> https://dipy.org/documentation/1.4.1./objects.inv/
generating gallery...
Using Sphinx-Gallery to convert rst text blocks to markdown for .ipynb files.
/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx_gallery/py_source_parser.py:105: DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead.
  if LooseVersion(sys.version) >= LooseVersion('3.7'):

[this warning was repeated several hundred times]

/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx_gallery/py_source_parser.py:105: DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead.
  if LooseVersion(sys.version) >= LooseVersion('3.7'):

generating MNE command help ... [100%] mne_what.py
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 56 source files that are out of date
updating environment: [new config] 786 added, 0 changed, 0 removed
reading sources... [100%] whats_new
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 16%] auto_tutorials/intro/10_overview
Traceback (most recent call last):
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, filenames)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/application.py", line 337, in build
    self.builder.build_update()
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 358, in build
    self.write(docnames, list(updated_docnames), method)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 532, in write
    self._write_serial(sorted(docnames))
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 542, in _write_serial
    self.write_doc(docname, doctree)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/builders/html/__init__.py", line 626, in write_doc
    self.docwriter.write(doctree, destination)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/writers/html.py", line 71, in translate
    self.document.walkabout(visitor)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/docutils/nodes.py", line 227, in walkabout
    if child.walkabout(visitor):
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/docutils/nodes.py", line 219, in walkabout
    visitor.dispatch_visit(self)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/sphinx/util/docutils.py", line 500, in dispatch_visit
    method(node)
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/pydata_sphinx_theme/bootstrap_html_translator.py", line 37, in visit_table
    if LooseVersion(sphinx.__version__) < LooseVersion("4.0"):
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/setuptools/_distutils/version.py", line 53, in __init__
    warnings.warn(
DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead.

Exception occurred:
  File "/Users/stephenzerfas/opt/anaconda3/envs/mnedev/lib/python3.9/site-packages/setuptools/_distutils/version.py", line 53, in __init__
    warnings.warn(
DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead.
The full traceback has been saved in /var/folders/42/yv_18zw16tz_w09fgdlj5p7w0000gr/T/sphinx-err-c7efnkya.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html_dev-noplot] Error 2
2

@mmagnuski I’m seeing lots of activity on responding to other posts but not this one. Does this mean I should have done something differently with this one? Apologies – brand new to the community.

Stephen

3

Hi @szerfas1,
I try to respond when I have something useful to say. :slight_smile: I never built the mne docs locally so I’m afraid I can’t help you with that.

1 Like
4

Makes sense. I’m relieved to know I haven’t obviously botched the question. I know I just polled you out of the blue - thanks for having a look.

5

But looking at the error more closely and the PR you linked - it looks that you are correct, the warning you experience should no longer be present on main (the main mne github branch, the most up-to-date development version). And in general, if you want to contribute to mne, working on the most up to date version (main) makes sense - I think you missed this step from the guide, where it advises to install a separate dev mne environment.