bleak
bleak copied to clipboard
hbldh
Bleak: WriteTheDocs session
Create better, more helpful documentation on ReadTheDocs.
Proposed layout of the new documentation:
- Introduction
- What Bleak is and what it isn't
- Basic Usage
- Scanning
- Connecting to one device
- Notifications
- Advanced usage
- Scanning
- BleakScanner
- Filtering
- Advertised data
- Client
- Connecting to multiple devices
- Reconnections
- Pairing
- Bleak SigSpec (#237)
- GUIs
- Scanning
- Differences between OSes
- Examples
- Changelog
- Contributing
- API (Interfaces)
As this has the "opinions appreciated" label, here is my view as someone who has only discovered bleak last week, and likes it a lot, but is struggling.
My first problem is that the API documentation is phrased in a way that is geared towards bleak developers, i.e. people implementing/extending bleak. This is probably due to the primary API consisting of the abstract classes to be subclassed and extended from the various backends. As an example, the definition of the BaseBleakClient, the first class you come across, is
The Client Interface for Bleak Backend implementations to implement.
The documentation of this interface should thus be safe to use as a reference for your implementation.
Whereas it would be much friendlier for users of bleak if this said something like The BleakClient represents a connection to a BLE device.
This may be fairly easily fixable by replacing the
from xxxxxx import xxxxBleakClient as BleakClient
in __init__.py with something like
from xxxxx import xxxxBleakClient as _BleakClientImplementation
class BleakClient(_BleakClientImplementation):
"""Insert user-friendly docstring here"""
My second problem is that the documentation is not complete. Again an example: the important bits in the BLEDevice object are the name and address attributes, but these are not documented anywhere, at least I could not find them. The metadata attribute is mentioned (at least for the MacOS backend) but the contents are not described.
My third problem (also mentioned in issue #277) as that it is difficult to work out how to combine functionality.
@jackjansen Thank you for the input!
I agree with the first part. It is due to API autogeneration issues, not being able to import all backends' code on the RTD build servers. I am reluctant to flip import order like you propose however. I plan on writing better docs without focusing on autogeneration instead.
The second problem is the main reason for this issue.
As for the third, I am not sure on what level to write the docs on. I do not want to write the code that people just copy. I want them to think and know what they do as well. But better, more collected examples not only in the Github folder but also on RTD is planned.
not being able to import all backends' code on the RTD build servers
Does autodoc_mock_imports not work around the problem?
Once again, this is not a feature I was aware of, thank you! It might definitely do the trick; I just assumed the problem was insoluble and moved on...
There is a need for a better documentation, with more examples that use up to date asyncio practices that make Bleak work optimally. A lot of issues drop in regarding GUIs, so a GUI section should be included as well:
- [ ] PyQT
- [ ] Tkinter
- [ ] Kivy
There is a need for a better documentation, with more examples that use up to date
asynciopractices that make Bleak work optimally. A lot of issues drop in regarding GUIs, so a GUI section should be included as well:
- [ ] PyQT
- [ ] Tkinter
- [ ] Kivy
I am strongly agree with you. I'm working in a GUI based in Pyqt5 and I'm using qasync but I experiment problems in disconnection/reconnection process. It's very frustrating because there's no clear examples using bleak in GUIs working properly. I'm evaluating to move to QBluetooth because that. Although, I 'm still thinking Bleak is a very good library for ble devices.
