search

armory3d / armsdk

Single-clone Armory SDK
37 stars 30 forks source link

Python api documentation #39

Closed tong closed 7 months ago

tong commented 2 years ago

It would be nice to have the armory python api documented. Maybe it could also improve code quality.

I've tried to use pdoc (→ https://tong.github.io/armsdk/blender/arm/) which is skipping a lot of code with errors (i think partly) related to usage of fake-bpy-module.

pdoc --html --output-dir api/blender armory/blender/arm --skip-errors

Since i am not familiar with any python doc generator, please tell me if you know a better tool or how to fix pdoc generation.

MoritzBrueckner commented 2 years ago

I tried the same with Sphinx a while ago and if I remember correctly that worked well. pdoc however seems to have a much nicer default template and to be able to directly preview the code is really cool!

One problem seems to be that we have a lot of code like register, unregister = bpy.utils.register_classes_factory(REG_CLASSES) at the end of the Python files, but because the bpy function is only fake and module-level code is run on import, Python executes this code and because there is no return value that could be unwrapped into two variables there is an exception.

If that's the only issue (which I doubt) there are ways around that though. For example we could define an environment variable if the API is built. Global code that depends on Blender functionality can then be wrapped inside a block that is only executed if there is no such environment variable set. That however might make the code less readable.

luboslenco commented 7 months ago

Cleaning up older issues, but PR still welcome.