OpenPype Code Documentation with Sphinx

[antirotor]

Code Documentation

(reboot)

This is fixing code documentation generation with Sphix. It is using Sphinx ApiDoc to crawl over our sources to generate rst -> html documentation.

How to generate documentation

From sources, run:

./.poetry/bin/poetry run python start.py make-api-docs

This will run the whole process, generating rst files from apidoc, then rst files for sphinx and then html files from rst files. You will find generated rst files in /docs/sources and html files in /docs/build/html.

❗ /docs/build is purged every time you run this command ❗

rst files are not overwritten by default. If you need to start from clean slate, delete all rst files in /docs/sources except index.rst.

---

Current state:

Currently docs generation is set to fail on warning. This allows us to fix problems in code and docstrings. It can be turned off with warningiserror=False in make_api_docs():openpype/cli.py on line 455. There you can also control other things that might help with debugging, like verbosity, etc.

Sphinx is configured by /docs/source/conf.py. One of the important settings right now is ignore_paths in run_apidoc() - this allows you to ignore whole path (or single file). This is useful because right now we are generating stuff from things we don't need to be in documentation (some vendor directories, and so on).

---

What to do next

We need to iterate over and over, fix issues in code and docstrings until there are no important warning. We also need to edit and curate particular rst files with stuff that isn't necessarily in docstrings.

[mkolar]

Task linked: OP-2318 API documentation

[antirotor]

First warning is on @iLLiCiTiT:

Warning, treated as error:
Cannot resolve cyclic import: openpype.api, openpype.settings, openpype.settings.entities, openpype.settings.entities.base_entity, openpype.lib, openpype.lib.execute, openpype.lib.log, openpype.lib

[iLLiCiTiT]

Script openpype/hosts/resolve/api/preload_console.py causes that building is stuck until Ctrl + C is pressed. Current traceback is unknown for me and didn't find out what is the issue.

[antirotor]

Current traceback is unknown for me and didn't find out what is the issue.

I think this is caused by that while True... loop. It gets executed even when imported. Could this be better refactored with if __name__ == "__main__": guard? @jakubjezek001

[mkolar]

@antirotor should we give this another go with the refactor of the client app? I highly doubt this will become mergable

[antirotor]

another unsuccessful shot at it. I hope v4 will have better luck with it.