mirror of
https://github.com/ynput/ayon-core.git
synced 2025-12-24 12:54:40 +01:00
74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
API Documentation
|
|
=================
|
|
|
|
This documents the way how to build and modify API documentation using Sphinx and AutoAPI. Ground for documentation
|
|
should be directly in sources - in docstrings and markdowns. Sphinx and AutoAPI will crawl over them and generate
|
|
RST files that are in turn used to generate HTML documentation. For docstrings we prefer "Napoleon" or "Google" style
|
|
docstrings, but RST is also acceptable mainly in cases where you need to use Sphinx directives.
|
|
|
|
Using only docstrings is not really viable as some documentation should be done on higher level - like overview of
|
|
some modules/functionality and so on. This should be done directly in RST files and committed to repository.
|
|
|
|
Configuration
|
|
-------------
|
|
Configuration is done in `/docs/source/conf.py`. The most important settings are:
|
|
|
|
- `autodoc_mock_imports`: add modules that can't be actually imported by Sphinx in running environment, like `nuke`, `maya`, etc.
|
|
- `autoapi_ignore`: add directories that shouldn't be processed by **AutoAPI**, like vendor dirs, etc.
|
|
- `html_theme_options`: you can use these options to influence how the html theme of the generated files will look.
|
|
- `myst_gfm_only`: are Myst parser option for Markdown setting what flavour of Markdown should be used.
|
|
|
|
How to build it
|
|
---------------
|
|
|
|
You can run:
|
|
|
|
```sh
|
|
cd .\docs
|
|
make.bat html
|
|
```
|
|
|
|
on linux/macOS:
|
|
|
|
```sh
|
|
cd ./docs
|
|
make html
|
|
```
|
|
|
|
This will go over our code and generate **.rst** files in `/docs/source/autoapi` and from those it will generate
|
|
full html documentation in `/docs/build/html`.
|
|
|
|
During the build you may see tons of red errors that are pointing to our issues:
|
|
|
|
1) **Wrong imports** -
|
|
Invalid import are usually wrong relative imports (too deep) or circular imports.
|
|
2) **Invalid docstrings** -
|
|
Docstrings to be processed into documentation needs to follow some syntax - this can be checked by running
|
|
`pydocstyle` that is already included with OpenPype
|
|
3) **Invalid markdown/rst files** -
|
|
Markdown/RST files can be included inside RST files using `.. include::` directive. But they have to be properly
|
|
formatted.
|
|
|
|
Editing RST templates
|
|
---------------------
|
|
Everything starts with `/docs/source/index.rst` - this file should be properly edited, Right now it just
|
|
includes `readme.rst` that in turn include and parse main `README.md`. This is entrypoint to API documentation.
|
|
All templates generated by AutoAPI are in `/docs/source/autoapi`. They should be eventually committed to repository
|
|
and edited too.
|
|
|
|
Steps for enhancing API documentation
|
|
-------------------------------------
|
|
|
|
1) Run `/docs/make.bat html`
|
|
2) Read the red errors/warnings - fix it in the code
|
|
3) Run `/docs/make.bat html` - again until there are no red lines
|
|
4) Edit RST files and add some meaningful content there
|
|
|
|
Resources
|
|
=========
|
|
|
|
- [ReStructuredText on Wikipedia](https://en.wikipedia.org/wiki/ReStructuredText)
|
|
- [RST Quick Reference](https://docutils.sourceforge.io/docs/user/rst/quickref.html)
|
|
- [Sphinx AutoAPI Documentation](https://sphinx-autoapi.readthedocs.io/en/latest/)
|
|
- [Example of Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
|
|
- [Sphinx Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html)
|