Initial documentation.

.gitlab-ci.yml

@@ -49,6 +49,23 @@ build-and-publish:
     - docker push ${MONGOEXPRESS_IMAGE}
     - docker push ${NGINX_IMAGE}
 
+pages:
+  stage: deploy
+  interruptible: true
+  image: python:3.10
+  before_script:
+  - pip install poetry
+  - cd backend
+  - poetry install
+  script:
+  - poetry run mkdocs build --strict --verbose
+  - mv site ../public
+  artifacts:
+    paths:
+    - public
+  rules:
+  - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+
 deploy-staging:
   stage: deploy
   interruptible: true
@@ -80,5 +97,3 @@ deploy-staging:
   after_script:
     - DOCKER_HOST=$OLD_DOCKER_HOST
     - docker context use default
-  only:
-    - main

backend/docs/contributing.md

@@ -0,0 +1,35 @@
+The sonoUno library uses [pre-commit](https://pre-commit.com) to ensure code quality and uniformity.
+To install the pre-commit hooks:
+
+```bash
+$ pip install --user pre-commit
+$ cd sonouno-server
+$ pre-commit install
+```
+
+The project also uses [poetry](https://python-poetry.org) to manage its package dependencies.
+To install poetry and a versioning plugin:
+```bash
+$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python
+$ ${XDG_DATA_HOME:-~/.local/share}/pypoetry/venv/bin/pip install poetry-dynamic-versioning
+```
+
+To install the project and its development dependencies:
+```bash
+$ cd backend
+$ poetry install
+```
+
+To run the project (inside the backend directory):
+```bash
+$ ../compose/run-dev.sh
+```
+In case of failure, check that on linux, the apache2 service is stopped:
+```bash
+$ sudo service apache2 stop
+```
+
+To run the test suite and activate the debugger in case of error:
+```bash
+$ ../compose/run-tests-backend.sh --pdb
+```

backend/docs/getting_started.md

@@ -0,0 +1,16 @@
+The sonoUno server APIs are described using [OpenAPI v3.1](https://www.openapis.org).
+They can be consulted at the url [http://api.sonouno.org.ar/redoc](http://api.sonouno.org.ar/redoc).
+
+To see an example showing how these APIs can be used, a dockerized [Jupyter notebook](https://gitlab.com/pchanial/sonouno-server/-/blob/main/backend/demo/demo_client.ipynb) has been made available. It uses the production server APIs to login a test user, to create a transform, to execute a job and to play the resulting audio file.
+
+```bash
+$ docker run --network host --rm pchanial/sonouno-server-demo
+```
+
+The technical stack is the following:
+
+- Docker compose for the container orchestration
+- FastAPI for the Python 3.10 web application
+- MongoDB for the user, transform and job database
+- MinIO, an S3-compatible object store, to serve the sonification outputs
+- Nginx to serve the application

backend/docs/index.md

@@ -0,0 +1,10 @@
+# Overview
+
+The sonoUno server provides RESTful APIs to
+
+- create transforms for sonification purposes.
+- execute a job that will execute a transform given specified inputs
+
+## Installation
+
+See the [contributing](contributing.md) section to install the project locally.

backend/mkdocs.yml

@@ -0,0 +1,29 @@
+site_name: sonoUno Library
+repo_name: pchanial/sonouno-library
+repo_url: https://gitlab.com/pchanial/sonouno-library
+
+theme:
+  name: material
+
+nav:
+- index.md
+- getting_started.md
+- contributing.md
+
+markdown_extensions:
+- pymdownx.highlight:
+    anchor_linenums: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.superfences
+- markdown_include.include:
+    base_path: examples
+- toc:
+    permalink: True
+- admonition
+
+plugins:
+- search
+- exclude:
+    glob:
+    - requirements.txt