running make html from docs directory fails

[craig8]

branch affected develop branch and develop branch with the non-auth pull request #2926 in it.

problem From a new environment execute the following

python3 bootstrap.py --documentation

Then cd into docs directory and run the following

(volttron) gridappsd@gridappsd_dev_2004:/repos/volttron/docs$ make html
Running Sphinx v5.1.1
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid language code. Falling back to 'en' (English).

Extension error:
Could not import extension m2r2 (exception: cannot import name 'ErrorString' from 'docutils.core' (/repos/volttron/env/lib/python3.8/site-packages/docutils/core.py))
make: *** [Makefile:20: html] Error 2

expected Documentation to be generated properly.

[Siecje]

That works for me with python --version == Python 3.9.10.

Since I'm using fish I had to activate the venv with source env/bin/activate.fish after running python3 bootstrap.py --documentation.

I do get a lot of warnings including the one you showed.

[craig8]

Interesting...I am using 3.8.10. I wonder if that's a difference?

[kefeimo]

stage 1: reproduce the error

Result: (ironically) since the process succeeded, and I couldn't reproduce the error message, i.e., "Could not import extension m2r2 (exception: cannot import name 'ErrorString' from 'docutils.core' (/repos/volttron/env/lib/python3.8/site-packages/docutils/core.py))"

Steps Follow reference Installing the Platform

• At a almost brand new Ubuntu 20.04 VM
• Run sudo apt-get update
• and run sudo apt-get install build-essential python3-dev python3-venv openssl libssl-dev libevent-dev git
• Run git clone https://github.com/VOLTTRON/volttron --branch develop
• Run cd volttron
• Run python 3 bootstrap.py --documentation
• Run source env/bin/activate
• Then cd doc, and run make html

stage 2: Diagnosis

Along the way, there are some errors/warning are interesting

• python 3 bootstrap.py —documentation Got "ERROR: sphinx-rtd-theme 1.0.0 has requirement docutils<0.18, but you'll have docutils 0.19 which is incompatible." Note: I didn't "fix" this error and continue to run the following steps.

• It seems the error message is related to m2r2 and docutils. Here are the package versions

  • m2r2==0.3.3
  • doctuils==0.19

Note: extra link

See more details at running make html from docs directory fails #2981 i.e., the full logs of the reproducing process. and pip list results.

TODO

Try out a newer version of Sphinx

[kefeimo]

As the following code snippet suggests in requirements.py

'documentation': ['mock',
                                    'sphinx-rtd-theme',
                                    'sphinx',
                                    'm2r2'],

Some observation

• The sphinx version is not fixed in Volttron. (at the time of the experiment, i.e., 08/14/2022, the sphinx version is 5.1.1)
• More probing on the track here are the package versions related to the "documentation"
  • mock==4.0.3
  • sphinx-rtd-theme==1.0.0
  • sphinx==5.1.1
  • m2r2==0.3.3

Note: from the sphinx release note It looks like the incompatible error "ERROR: sphinx-rtd-theme 1.0.0 has requirement docutils<0.18, but you'll have docutils 0.19 which is incompatible." might be a false alarm

Conclusion

• Seek more info about the dependency version of the Volttron environment that encountered the issue
• A potential solution is by fixing the dependency version in requirements.py

[craig8]

This seems like an issue that is corrected by upgrading m2r2 from 0.3.2 to 0.3.3. It appears that bootstrap.py doesn't --upgrade when things are not pinned like the develop branch isn't (for most things).