Documentation

[uzlonewolf]

One thing that's always annoyed me about TinyTuya is the lack of documentation. One day I'd be using the good documentation for something like pySerial and the next I'd be digging through TinyTuya source code files 🤣 So, I got the Sphinx code-to-documentation generator set up along with Read The Docs for web display. It's still very, very rough as I spent the last 2 days fighting with Sphinx to get it to link everything correctly, but the TinyTuya function definitions imported surprisingly well as-is without me needing to rewrite anything.

PoC: https://tinytuya-lw.readthedocs.io/

It's still really rough, but it's a start. I think the next thing I'm going to work on is adding type hinting to all the functions (which is going to require Python 3.5+).

[jasonacox]

Ooooo! Love this! I see only conflict is version. Are you updating that?

[uzlonewolf]

Yeah, I had bumped the version which in hindsight wasn't needed as there aren't really any code changes, only comment changes. I also reworked how it sets the version string while I was in there to match what was wanted in #588 but I'll probably pull it out and save that for a different PR. Or you can do it the next time the version needs to be bumped.

I noticed this merge conflict yesterday but didn't fix it as I ran into a different issue that needs some discussion before moving forward:

Sphinx gets confused and cannot generate links when a class has the same name as the module (filename) it is in. Initially I had solved this by moving Cloud and BulbDevice et al to new files with different names, however I later realized this will break imports if someone is doing i.e. import tinytuya.Cloud (though from tinytuya import Cloud still works). If it weren't for the Cloud module I'm not sure how much this would matter as import tinytuya.Device has never worked.

I just discovered a different workaround that would allow leaving all the files as they are now at the expense of linking functions as project.module.class.function, i.e. Cloud's setregion() becomes tinytuya.Cloud.Cloud.setregion(). I'm still digging to see if there's anything else I can do.

[jasonacox]

I also reworked how it sets the version string while I was in there to match what was wanted in #588 but I'll probably pull it out and save that for a different PR. Or you can do it the next time the version needs to be bumped.

Thanks yes, I agree. It breaks my automation (which I just need to fix).

Sphinx gets confused and cannot generate links when a class has the same name as the module (filename) it is in.

To be honest, that sounds like a weakness (bug?) in Sphinx that needs to be addressed there, not by rewriting our structure.

I'll start walking through the commits. Let me know when you think this is ready.

[jasonacox]

Makes sense

[uzlonewolf]

To be honest, that sounds like a weakness (bug?) in Sphinx that needs to be addressed there, not by rewriting our structure.

I agree. Unfortunately they can't/won't fix it. I found one issue where someone (I have no idea if they are involved with the project or are just some rando) was basically bragging about how "over 100 people have opened issues due to this problem and all those people are wrong!" I'm still working on it though and have been digging through the Sphinx source code looking for a way to monkey-patch around it or something. Fixing it for the *Device classes was rather easy, it's the constants/direct attributes which are kicking my butt.

[uzlonewolf]

It's a kludge, but it appears to work. Fortunately it only messes with Sphinx so even if it breaks it's not a big deal.