[#82348] Add API docs

Author: msobkowski

.github/docs-template/requirements.txt

@@ -1,2 +1,3 @@
 https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip
 pydantic==2.4.2 #2.5.0 causes AttributeError during sphinx execution
+sphinxcontrib-httpdomain

.github/docs-template/source/api.rst

@@ -0,0 +1,32 @@
+
+Protoplaster Server API Reference
+---------------------------------
+
+Error Handling
+~~~~~~~~~~~~~~
+
+Should an error occur during the handling of an API request, either because of incorrect request data or other endpoint-specific scenarios, the server will return an error structure containing a user-friendly description of the error.
+An example error response is shown below:
+
+.. sourcecode:: json
+
+   {
+      "error": "test start failed"
+   }
+
+
+Configs API
+~~~~~~~~~~~
+
+.. autoflask:: protoplaster.protoplaster:create_docs_app()
+   :modules: protoplaster.api.v1.configs
+   :undoc-static:
+   :order: path
+
+Test Runs API
+~~~~~~~~~~~~~
+
+.. autoflask:: protoplaster.protoplaster:create_docs_app()
+   :modules: protoplaster.api.v1.test_runs
+   :undoc-static:
+   :order: path

.github/docs-template/source/conf.py

@@ -37,6 +37,8 @@
 
 # If you need to add extensions just add to those lists
 extensions = default_extensions
+extensions.append('sphinxcontrib.autohttp.flask')
+extensions.append('sphinxcontrib.autohttp.flaskqref')
 myst_enable_extensions = default_myst_enable_extensions
 myst_fence_as_directive = default_myst_fence_as_directive
 

.github/docs-template/source/index.md

@@ -4,6 +4,7 @@
 :maxdepth: 2
 
 introduction
+api
 readme
 protoplaster
 report

.github/docs-template/source/introduction.md

@@ -2,7 +2,9 @@
 
 This documentation serves as an example of how individual projects documentation can look like.
 
-The second chapter contains information from the README file.
+The second chapter contains reference of remote API when running Protoplaster in server mode.
+
+The third chapter contains information from the README file.
 
 The last chapter is generated from the sample ``test.yml`` file which can be found in the README.
 Its purpose is to demonstrate the documentation generated to describe test procedures used in a project.

.github/scripts/latex.sh

@@ -8,6 +8,7 @@ python3 -m venv ./venv
 . ./venv/bin/activate
 
 pip3 install -r requirements.txt
+pip3 install ../
 
 cd build/latex
 LATEXMKOPTS='-interaction=nonstopmode' make

.github/scripts/sphinx.sh

@@ -8,6 +8,7 @@ python3 -m venv ./venv
 . ./venv/bin/activate
 
 pip3 install -r requirements.txt
+pip3 install ../
 
 make html latex
 

protoplaster/protoplaster.py

@@ -42,6 +42,18 @@
 app = Flask(__name__)
 
 
+def create_docs_app() -> Flask:
+    """Create an app that can be used for building the docs
+
+    This only registers the available API routes, this cannot be used to run
+    the server! Used for dynamically building the API reference chapter in
+    the documentation.
+    """
+    app = Flask(__name__)
+    app.register_blueprint(protoplaster.api.v1.create_routes())
+    return app
+
+
 init()