docs: add gh_pages documentation

.gitignore

@@ -138,4 +138,5 @@ dmypy.json
 
 # Project specific
 
-data/images
+data/images
+gh_pages

Dockerfile

@@ -80,6 +80,6 @@ COPY .flake8 pyproject.toml ./
 # create folders that we mount in dev to avoid permission problems
 USER root
 RUN \
-    mkdir -p /opt/open-prices/.cov && \
-    chown -R off:off /opt/open-prices/.cov
+    mkdir -p /opt/open-prices/.cov /opt/open-prices/docs /opt/open-prices/gh_pages && \
+    chown -R off:off /opt/open-prices/.cov /opt/open-prices/docs /opt/open-prices/gh_pages
 USER off

Makefile

@@ -13,6 +13,9 @@ export COMPOSE_DOCKER_CLI_BUILD=1
 COMPOSE_PROJECT_NAME ?= $(shell grep COMPOSE_PROJECT_NAME ${ENV_FILE} | cut -d '=' -f 2)
 DOCKER_COMPOSE=docker-compose --env-file=${ENV_FILE}
 
+# avoid target corresponding to file names, to depends on them
+.PHONY: *
+
 #------------#
 # Production #
 #------------#
@@ -76,6 +79,40 @@ log:
 	${DOCKER_COMPOSE} logs -f api
 
 
+#------------#
+# Quality    #
+#------------#
+toml-check:
+	${DOCKER_COMPOSE} run --rm --no-deps api poetry run toml-sort --check pyproject.toml
+
+toml-lint:
+	${DOCKER_COMPOSE} run --rm --no-deps api poetry run toml-sort --in-place pyproject.toml
+
+flake8:
+	${DOCKER_COMPOSE} run --rm --no-deps api flake8
+
+black-check:
+	${DOCKER_COMPOSE} run --rm --no-deps api black --check .
+
+black:
+	${DOCKER_COMPOSE} run --rm --no-deps api black .
+
+mypy:
+	${DOCKER_COMPOSE} run --rm --no-deps api mypy .
+
+isort-check:
+	${DOCKER_COMPOSE} run --rm --no-deps api isort --check .
+
+isort:
+	${DOCKER_COMPOSE} run --rm --no-deps api isort .
+
+docs:
+	@echo "🥫 Generationg doc…"
+	${DOCKER_COMPOSE} run --rm --no-deps api ./build_mkdocs.sh
+
+checks: toml-check flake8 black-check mypy isort-check docs
+
+
 #------------#
 # Production #
 #------------#

build_mkdocs.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set -euo pipefail
+IFS=$'\n\t'
+
+
+# Build mkdocs
+poetry run mkdocs build --strict

docker/dev.yml

@@ -10,6 +10,13 @@ x-api-base: &api-base
   volumes:
     # mount code dynamically
     - "./app:/opt/open-prices/app"
+    - ./pyproject.toml:/opt/open-prices/pyproject.toml
+    # make doc generation available
+    - ./mkdocs.yml:/opt/open-prices/mkdocs.yml
+    - ./build_mkdocs.sh:/opt/open-prices/build_mkdocs.sh
+    - ./README.md:/opt/open-prices/README.md
+    - ./docs:/opt/open-prices/docs
+    - ./gh_pages:/opt/open-prices/gh_pages
 
 services:
   api:

docs/README.md

@@ -0,0 +1,8 @@
+# Open Prices
+
+Open Prices is a project to collect and share prices of food products around the world.
+
+It consists of:
+
+- a REST API, built using [FastAPI](https://fastapi.tiangolo.com/)
+- a PostgreSQL database

mkdocs.yml

@@ -0,0 +1,22 @@
+# Where to find documentation
+docs_dir: docs
+
+# Link to Github on every page
+repo_url: https://github.com/openfoodfacts/open-prices
+edit_uri: blob/main/docs/
+
+site_name: Open Prices
+site_dir: gh_pages
+
+theme:
+  name: material
+
+markdown_extensions:
+  - footnotes
+  - mdx_truly_sane_lists
+  - pymdownx.highlight
+  - pymdownx.superfences
+
+plugins:
+  - awesome-pages
+  - search