Fix autodocs

[tannewt]

I don't think the docs are setup to get all of the comments pulled into read the docs. I think this requires a static file to point to each class. I haven't done it recently.

These pages should have more info: https://circuitpython.readthedocs.io/projects/ble/en/latest/uuid.html

[FoamyGuy]

Strangely this page seems to generate fine locally when built with sphinx:

I have run across things like this a few times where the results from building locally with sphinx differ from the results that readthedocs ends up publishing.

[FoamyGuy]

It also seems like maybe there are two instances of the BLE library in readthedocs? I found this one which uses a different sub-domain in the URL, and it does also contain the content on the uuid page: https://circuitpython-ble.readthedocs.io/en/latest/uuid.html

[FoamyGuy]

It turns out the circuitpython-ble.readthedocs.io is a different project perhaps created a while ago by accident. So while their pages do look correct, I don't think it's actually relevant to the issue noted here.

Looking into the build logs for the current RTD project for this library: https://readthedocs.org/projects/adafruit-circuitpython-ble/builds/15293278/

I notice there are several instances of errors similar to this:

WARNING: autodoc: failed to import module 'advertising.standard' from module 'adafruit_ble'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/adafruit-circuitpython-ble/envs/latest/lib/python3.6/site-packages/sphinx/ext/autodoc/importer.py", line 70, in import_module
    return importlib.import_module(modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/adafruit-circuitpython-ble/envs/latest/lib/python3.6/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 994, in _gcd_import
  File "<frozen importlib._bootstrap>", line 971, in _find_and_load
  File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 665, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 678, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/adafruit-circuitpython-ble/checkouts/latest/adafruit_ble/__init__.py", line 21, in <module>
    import _bleio
  File "/home/docs/checkouts/readthedocs.org/user_builds/adafruit-circuitpython-ble/envs/latest/lib/python3.6/site-packages/_bleio/__init__.py", line 18, in <module>
    from _bleio.address import Address
  File "/home/docs/checkouts/readthedocs.org/user_builds/adafruit-circuitpython-ble/envs/latest/lib/python3.6/site-packages/_bleio/address.py", line 13
    from __future__ import annotations
                                     ^
SyntaxError: future feature annotations is not defined

I'm not seeing these errors when I run the build locally. Thinking perhaps the core stubs, or something else I have installed could cause a difference, I also tried in a venv with only the things listed in requirements.txt and docs/requirements.txt installed in it. But that build also did not result in the above errors for me locally. And the pages do contain all of their content (though the theme was different).

I'm thinking it's possible that these errors are causing some of the pages not to build properly inside RTD which may be leading to the missing content on those pages.

Another observation is that the RTD builds are occurring on python 3.6. My local build attempts were 3.8. Maybe that difference could be related to the errors and this issue.

[FoamyGuy]

I do think the crux of this issue is the RTD build happening on python 3.6. I'm not very familar with the usage of __future__ but I did find an answer here: https://stackoverflow.com/a/52890129/507810 indicating that 3.7 is the minimum version of python where this is available.

Based on that, and the fact that my local builds under python 3.8 seem to generate the pages correctly I think if we update the version here:

Adafruit_CircuitPython_BLE/.readthedocs.yaml

Line 12 in 5b4f87f

version: "3.6"

To 3.7 or newer the build may be able to complete successfully and include content on all of the pages.

[tannewt]

@FoamyGuy Thanks for the debugging! Want to make a PR to bump the python version?

[FoamyGuy]

The newest RTD build after the merge looks good now. The page linked in the first comment of this issue does now show the expected content within it. 🎉

I will check into the bundle libraries to find if / how many have differently named config files (.yml vs. .yaml) and see if there is a way to more easily sweep all libraries and update them to have matching versions.

[tannewt]

Thank you @FoamyGuy!