Documentation doesn't build with sphinx >= 2.0

[daveminh]

Expected behavior

Documentation would build and I could see it in doc/html/index.html, as described here: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

Actual behavior

Attempting to autodetect OpenMP support... Did not detect OpenMP support.
No openmp compatible compiler found default to serial build.
Will attempt to use Cython.
/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/setuptools/dist.py:454: UserWarning: Normalizing '0.20.2-dev0' to '0.20.2.dev0'
warnings.warn(tmpl.format(**locals()))
running build_sphinx
Running Sphinx v3.0.2
loading intersphinx inventory from https://docs.python.org/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/numpy/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/reference/objects.inv...
loading intersphinx inventory from https://matplotlib.org/objects.inv...
loading intersphinx inventory from https://networkx.github.io/documentation/stable/objects.inv...
loading intersphinx inventory from https://www.mdanalysis.org/GridDataFormats/objects.inv...
loading intersphinx inventory from https://gsd.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://parmed.github.io/ParmEd/html/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: all of 0 po files
building [html]: all source files
updating environment: [new config] 146 added, 0 changed, 0 removed
reading sources... [ 9%] documentation_pages/analysis/encore/dimensionality_red/Users/dminh/Documents/GitHub/mdanalysis/package/MDAnalysis/analysis/hbonds/hbond_analysis.py:345: DeprecationWarning: This module is deprecated as of MDAnalysis version 1.0.It will be removed in MDAnalysis version 2.0Please use MDAnalysis.analysis.hydrogenbonds.hbond_analysis instead.
category=DeprecationWarning
reading sources... [100%] index
sphinx-sitemap warning: No pages generated for sitemap.xml

Warning, treated as error:
/Users/dminh/Documents/GitHub/mdanalysis/package/MDAnalysis/analysis/encore/similarity.py:docstring of MDAnalysis.analysis.encore.similarity.ces:1:duplicate object description of MDAnalysis.analysis.encore.similarity.ces, other instance in documentation_pages/analysis/encore/similarity, use :noindex: for one of them

Code to reproduce the behavior

python setup.py build_sphinx -E

Current version of MDAnalysis

• Which version are you using? (run python -c "import MDAnalysis as mda; print(mda.__version__)")

0.20.2-dev0

• Which version of Python (python -V)?

Python 3.6.10

• Which operating system?

Mac OS X 10.14.6

[orbeckst]

Thanks for noting the build issue. This seems easy enough to fix in the encore docs.

I am wondering why our travis tests for docs are not catching this problem, given that we run python setup.py build_sphinx ...

mdanalysis/.travis.yml

Lines 51 to 58 in 400f93c

	- env: NAME="Doc"
	MAIN_CMD="cd package && python setup.py"
	SETUP_CMD="build_sphinx"
	PYTHON_VERSION=3.7
	BUILD_DOCS=true
	BUILD_CMD="cd ${TRAVIS_BUILD_DIR}/package && python setup.py build_ext --inplace"
	INSTALL_HOLE="false"
	PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx==1.8.5 sphinx-sitemap sphinx_rtd_theme"

... and I thought the -E was implied somewhere.

[lilyminium]

Are you running sphinx 3.0.2-ish? For me, 3.0.3 is unhappy when:

• the .rst files autodocument a module with members, when the module docstring also autoclasses or autofunctions something
• a class docstring documents methods that have their own docstring, or an attribute with its own docstring

The test suite installs 1.8.5 and that builds the docs fine for me. A lot of modules and classes do the above, so it looks like upgrading Sphinx will be a bother.

[orbeckst]

I had to downgrade sphinx<3.0 for the docs to build locally.

(I also get a warning for the doc string of lib.ProgressBar which is inherited from tqdm.tqdm – so we don't even control the reST – and I have to allow warnings in order to build the docs).

[lilyminium]

I got that tqdm warning too -- I believe 1.8.5 removed that for me.

[daveminh]

Running Sphinx v3.1.1

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
File "/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/sphinx/config.py", line 319, in eval_config_file
execfile_(filename, namespace)
File "/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 88, in execfile_
exec(code, _globals)
File "/Users/dminh/Documents/GitHub/mdanalysis/package/doc/sphinx/source/conf.py", line 18, in
import msmb_theme # for little versions pop-up
ModuleNotFoundError: No module named 'msmb_theme'

[daveminh]

(mdanalysis-dev) Minh-IIT-MBP2018:[~/Documents/GitHub/mdanalysis/package]: conda install sphinx=2.4.4
Collecting package metadata (current_repodata.json): done
Solving environment: done

Package Plan

environment location: /miniconda2/envs/mdanalysis-dev

added / updated specs:
- sphinx=2.4.4

The following packages will be DOWNGRADED:

sphinx 3.1.1-py_0 --> 2.4.4-py_0

Proceed ([y]/n)? y

Preparing transaction: done
Verifying transaction: done
Executing transaction: done
(mdanalysis-dev) Minh-IIT-MBP2018:[~/Documents/GitHub/mdanalysis/package]: python setup.py build_sphinx -E
Attempting to autodetect OpenMP support... Did not detect OpenMP support.
No openmp compatible compiler found default to serial build.
Will attempt to use Cython.
/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/setuptools/dist.py:454: UserWarning: Normalizing '2.0.0-dev0' to '2.0.0.dev0'
warnings.warn(tmpl.format(**locals()))
running build_sphinx
Running Sphinx v2.4.4

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
File "/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/sphinx/config.py", line 348, in eval_config_file
execfile_(filename, namespace)
File "/miniconda2/envs/mdanalysis-dev/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 81, in execfile_
exec(code, _globals)
File "/Users/dminh/Documents/GitHub/mdanalysis/package/doc/sphinx/source/conf.py", line 18, in
import msmb_theme # for little versions pop-up
ModuleNotFoundError: No module named 'msmb_theme'

[daveminh]

pip install msmb_theme clears the error. add a dependency somewhere?

[daveminh]

I had to downgrade sphinx<3.0 for the docs to build locally.

(I also get a warning for the doc string of lib.ProgressBar which is inherited from tqdm.tqdm – so we don't even control the reST – and I have to allow warnings in order to build the docs).

How do you allow warnings?

[lilyminium]

pip install msmb_theme clears the error. add a dependency somewhere?

Yeah sorry about that @daveminh, this dependency was very recently added to the library.

How do you allow warnings?

Try building with make html SPHINXBUILD="sphinx-build -v". Here you're overriding the -W flag in the Makefile that converts warnings to errors in the first place.

[daveminh]

What directory would you run that in?
...

Warning, treated as error:
/Users/dminh/Documents/GitHub/mdanalysis/package/MDAnalysis/lib/log.py:docstring of MDAnalysis.lib.log.ProgressBar:69:Unexpected indentation.

(mdanalysis-dev) Minh-IIT-MBP2018:[~/Documents/GitHub/mdanalysis/package]: make html SPHINXBUILD="sphinx-build -v"
make: *** No rule to make target `html'. Stop.

[daveminh]

Never mind I tried it in mdanalysis/package/doc/sphinx/ and it worked.