From 2fdb0ece6b43503b490beb2a83bb40a74e0883f0 Mon Sep 17 00:00:00 2001
From: Ondrej Samohel <ondrej.samohel@orbi.tools>
Date: Fri, 3 Mar 2023 17:18:50 +0100
Subject: [PATCH] :memo: add documentation about building documentation

---
 docs/README.md      | 74 +++++++++++++++++++++++++++++++++++++++++++++
 docs/source/conf.py |  5 ---
 2 files changed, 74 insertions(+), 5 deletions(-)
 create mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..102da990aa
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,74 @@
+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)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4d20fbb3d1..916a397e8e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -258,9 +258,4 @@ intersphinx_mapping = {
     'https://docs.python.org/3/': None
 }
 
-# -- Options for todo extension ----------------------------------------------
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
-
 myst_gfm_only = True