add addtional RTD info

[tcfranks]

resolves #56

submitted for initial review and comment

[tcfranks]

note: I did not do the base object, since I'm looking for feedback on how far I missed the mark on these three. I anticipate directions to complete the base, if we feel that should be done.....

[jposada202020]

Hello :), thanks for the add I could take a look adn we could work together, there is one thing that needs to be added in order to show the documentation in the __init__ in read the docs. at the moment, the docs are like this

in order to show the changes that you are doing, we need to add the following line in conf.py in the docs directory, in https://github.com/adafruit/Adafruit_CircuitPython_PN532/blob/0061f33008bf02381232ba1c7aec960ab98af18d/docs/conf.py#L41

autoclass_content = "both"

This would generate the documentation after merging the changes that you are proposing like this:

You could check the effect of building the docs locally. If you have any question please feel free either here or in discord :)

[tcfranks]

@jposada202020 you mentioned building the docs locally and reviewing - what process does that? If you can even point to a link I'm willing to dig a bit more.

[jposada202020]

@tcfranks hello:) hello you will need to install sphinx, and sphinx-rtd-theme with a pip command, nothing very complicated for instructions https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs You will change to the docs directory in your clone repo and do the command sphinx-build -E -W -b html . _build/html and then read the API.html in your preferred browser. It is very nice, and you could see the effects of any changes without the need of the CI in seconds :)

[tcfranks]

@jposada202020 I have a problem running the sphinx-build command. It seems not to see items imported inside the try block. Moved the first two outside just to test (digitalio.DigitalInOut and circuitpython-typing.ReadableBuffer. It then fails because the typing library isn't found. so it appears it's not quite as straightforward as the docs are suggesting. Any ideas?

[tcfranks]

error examples (most recent first) Warning, treated as error: autodoc: failed to import module 'adafruit_pn532' from module 'adafruit_pn532'; the following exception was raised: No module named 'circuitpython_typing'

File "C:\Users\Thomas\PycharmProjects\Adafruit_CircuitPython_PN532\adafruit_pn532\adafruit_pn532.py", line 157, in class PN532: File "C:\Users\Thomas\PycharmProjects\Adafruit_CircuitPython_PN532\adafruit_pn532\adafruit_pn532.py", line 275, in PN532 params: ReadableBuffer = b"", NameError: name 'ReadableBuffer' is not defined

File "", line 241, in _call_with_frames_removed File "C:\Users\Thomas\PycharmProjects\Adafruit_CircuitPython_PN532\adafruit_pn532\adafruit_pn532.py", line 159, in class PN532: File "C:\Users\Thomas\PycharmProjects\Adafruit_CircuitPython_PN532\adafruit_pn532\adafruit_pn532.py", line 166, in PN532 irq: Optional[DigitalInOut] = None, NameError: name 'DigitalInOut' is not defined

[jposada202020]

@tcfranks are you working in a virtual environment? there could be two problems according to my experience: Update sphinx to 6.X.X. in the library docs directory requirements.txt we request sphinx>=4.0.0

Also as you could see in the requirements.txt you have the following requirements. So you can install them in your virtual environment

Adafruit-Blinka
adafruit-circuitpython-busdevice
adafruit-circuitpython-typing
pyserial
typing-extensions~=4.0

I have reproduced the error that your are having, eliminating typing-extensions from my virtual environment.

(venv) j@j:~/PycharmProjects/Adafruit_CircuitPython_PN532/docs$ sphinx-build -E -W -b html . _build/html
Running Sphinx v6.1.3
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.circuitpython.org/projects/busdevice/en/latest/objects.inv...
loading intersphinx inventory from https://docs.circuitpython.org/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                            

Warning, treated as error:
autodoc: failed to import module 'adafruit_pn532' from module 'adafruit_pn532'; the following exception was raised:
Traceback (most recent call last):
  File "/home/j/circuitpython projects/venv/lib/python3.10/site-packages/sphinx/ext/autodoc/importer.py", line 60, in import_module
    return importlib.import_module(modname)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/home/j/PycharmProjects/Adafruit_CircuitPython_PN532/adafruit_pn532/adafruit_pn532.py", line 159, in <module>
    class PN532:
  File "/home/j/PycharmProjects/Adafruit_CircuitPython_PN532/adafruit_pn532/adafruit_pn532.py", line 166, in PN532
    irq: Optional[DigitalInOut] = None,
NameError: name 'DigitalInOut' is not defined

(venv) j@j:~/PycharmProjects/Adafruit_CircuitPython_PN532/docs$ pip install typing-extensions
Collecting typing-extensions
  Using cached typing_extensions-4.5.0-py3-none-any.whl (27 kB)
Installing collected packages: typing-extensions
Successfully installed typing-extensions-4.5.0
(venv) j@j:~/PycharmProjects/Adafruit_CircuitPython_PN532/docs$ sphinx-build -E -W -b html . _build/html
Running Sphinx v6.1.3
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.circuitpython.org/projects/busdevice/en/latest/objects.inv...
loading intersphinx inventory from https://docs.circuitpython.org/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                            
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                             
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.
(venv) j@j:~/PycharmProjects/Adafruit_CircuitPython_PN532/docs$ 

[jposada202020]

It seems that It did not like very much my space add, and now the CI is failing because of that. could you check on your end. thanks

[tcfranks]

@jposada202020 I still error out with same errors and no html pages get built. Running Sphinx v6.1.3 Where does this leave us? Is there someone else that can help us out?

[tcfranks]

@kattni this is the project - or do you need my side of the branch?

[jposada202020]

Thank you!