Documenting zigpy API a kind of developer guide

[pipiche38]

Purpose if to document the zigpy API and the key elements and steps to use zigpy library

[coveralls]

Coverage remained the same at 99.98% when pulling 31e67ce on pipiche38:patch-2 into bc1040f on zigpy:dev.

[pipiche38]

please feel free to add/change ...

[Hedda]

@Adminiuga @dmulcahey @puddly this is a continuation of the long discussion in #452 and to some also relates to parts in #471

[Hedda]

Not sure if it is a good idea to maybe put in some empty placeholder section with 'TO-DO' and/or 'Help-wanted' comments?

@pipiche38 wrote this below in #471 about what he would like in a 'getting started' guide:

Here is the summary of a refection I had after trying to build a poc for Domoticz. This is not about documenting the code itself, but more how to start.
Maybe it is just about creating the file, and then having everyone contributing to it.

I would be more than happy to handle and challenge the content.

As a library you need to provide some guide on how-to use such library. I tried with #470, but I don't think we understand each other.

Just have a look to https://www.domoticz.com/wiki/Developing_a_Python_plugin which describe the steps on how to develop a plugin in Domoticz.

What I would expect from a Zigpy Developer Guide are:

1- Concepts

• What are the zigpy principle. What does it do (from pairing a device, to handling of messages).

• The usage of asyncio and the development consequences

• how to receive messages from devices (flow)

  • receiving attributes values
  • receiving commands

• how to send command to devices (flow)

• the concept of listner

• How to deal with the Zigbee radio sub libraries

• Zigpy radio schema (which affects configuration options ) - see RFC: Zigpy/API/Radio schemas #381

• how to use quirks

2- My first App using zigpy

• create the PersistentDB and open the zigbee radio (BTW, I don't understand what the 2 are linked together; I would expect (i) PersistentDB (ii) Zigbee radio communication)
• Loading the DB and adding listener
• setting the call back methods

3- API list

4- How to deal with errors

[Gamester17]

@pipiche38 I like to suggest also looking at the README.md from zsmartsystems/com.zsmartsystems.zigbee for inspiration:

https://github.com/zsmartsystems/com.zsmartsystems.zigbee/blob/master/README.md

[Hedda]

@pipiche38 please also see the somewhat related replies from @puddly to @Mopele in zigpy/zigpy-znp#25

[Hedda]

@Adminiuga and @puddly What is your input and/or feedback on this documentation file?

[Hedda]

@Adminiuga should this maybe just be merged 'as-is' to at least have a starting point of text to build the documentation from?

[Hedda]

FYI, there is now a wiki available for zigpy now here -> https://github.com/zigpy/zigpy/wiki

[pipiche38]

wonder if that is still up to date as it has not been updated since a year

[Hedda]

Maybe better to merge this as-is than not to have any API documentation at all?