make docs failing

[jackjansen]

• bleak version: develop HEAD
• Python version: 3.9.13
• Operating System: macOS 12.4
• BlueZ version (bluetoothctl -v) in case of Linux:

Description

Trying to build the documentation. Actually because I want to try it on another branch I'm working on, where it failed, then I tried on develop, where it fails too.

What I Did

git checkout develop
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements_dev.txt
make docs

The output:

(.venv) jack@beignet:bleak$ make docs
rm -f docs/bleak.rst
rm -f docs/modules.rst
sphinx-apidoc -o docs/ bleak
Creating file docs/bleak.rst.
File docs/bleak.backends.rst already exists, skipping.
File docs/bleak.backends.bluezdbus.rst already exists, skipping.
File docs/bleak.backends.corebluetooth.rst already exists, skipping.
File docs/bleak.backends.p4android.rst already exists, skipping.
File docs/bleak.backends.winrt.rst already exists, skipping.
Creating file docs/modules.rst.
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C docs clean
rm -rf _build/*
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C docs html
sphinx-build -b html -W -d _build/doctrees   . _build/html
Running Sphinx v5.1.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: [new config] 21 added, 0 changed, 0 removed
reading sources... [ 52%] bleak.backends.corebluetooth                                                                                                                                 
Warning, treated as error:
/Users/jack/src/jack-git/bleak/bleak/exc.py:docstring of bleak.exc:1:duplicate object description of bleak.exc, other instance in api, use :noindex: for one of them
make[1]: *** [html] Error 2
make: *** [docs] Error 2

[dlech]

Readthedocs is passing, so I'm guessing this must have to do with the Sphinx version. It still uses the default Sphinx v1.8.6.

[jackjansen]

I was apparently using Sphinx 5.1.0 (which satisfies requirements_dev.txt).

Pinning Sphinx==1.8.6 leads to a different error:

(.venv) jack@beignet:bleak$ make docs
rm -f docs/bleak.rst
rm -f docs/modules.rst
sphinx-apidoc -o docs/ bleak
Traceback (most recent call last):
  File "/Users/jack/src/jack-git/bleak/.venv/bin/sphinx-apidoc", line 5, in <module>
    from sphinx.ext.apidoc import main
  File "/Users/jack/src/jack-git/bleak/.venv/lib/python3.9/site-packages/sphinx/ext/apidoc.py", line 32, in <module>
    from sphinx.cmd.quickstart import EXTENSIONS
  File "/Users/jack/src/jack-git/bleak/.venv/lib/python3.9/site-packages/sphinx/cmd/quickstart.py", line 49, in <module>
    from sphinx.util.template import SphinxRenderer
  File "/Users/jack/src/jack-git/bleak/.venv/lib/python3.9/site-packages/sphinx/util/template.py", line 17, in <module>
    from sphinx.jinja2glue import SphinxFileSystemLoader
  File "/Users/jack/src/jack-git/bleak/.venv/lib/python3.9/site-packages/sphinx/jinja2glue.py", line 16, in <module>
    from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, \
ImportError: cannot import name 'contextfunction' from 'jinja2' (/Users/jack/src/jack-git/bleak/.venv/lib/python3.9/site-packages/jinja2/__init__.py)
make: *** [docs] Error 1

[dlech]

ImportError: cannot import name 'contextfunction' from 'jinja2'

https://stackoverflow.com/q/71634462/1976323

I guess the jinja2 version needs to be pinned as well.

[jackjansen]

The issue seems to be with the toplevel Makefile. And maybe only on MacOS: if I don't install the requirements.txt and hence don't have pyobjc-framework-CoreBluetooth the problem doesn't occur, at least: as long as I run READTHEDOCS=True make -C docs html only.

But if I do have the corebluetooth module installed, and I run a toplevel make docs I get some extra files in docs such as bleak.backends.corebluetooth.rst, and from that point on things start failing.

Hmm.... would it be the sphinx-apidoc -o docs/ bleak that is the culprit?

[jackjansen]

Indeed, I think the sphinx-apidoc is a leftover from the past. git blame shows it as

^2e7bb43 (Henrik Blidh 2018-04-26 23:12:47 +0200 69)    sphinx-apidoc -o docs/ bleak

but in 2020 docs/api.rst was updated to include the relevant bits manually:

07d07a04 (Henrik Blidh  2020-09-14 15:31:39 +0200  21)

[dlech]

I've never used the top-level makefile, so I would be OK with just deleting the whole file.

[dlech]

These issues have been addressed in 78f15ee and 74c29ff.