master > master: code py - documentation generation

code/python/justfile

@@ -12,6 +12,7 @@ _default:
 
 PYTHON := if os_family() == "windows" { "py -3" } else { "python3" }
 GEN_MODELS := "datamodel-codegen"
+GEN_MODELS_DOCUMENTATION := "openapi-generator"
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Macros
@@ -56,6 +57,16 @@ _generate-models path name:
         --input {{path}}/{{name}}-schema.yaml \
         --output {{path}}/generated/{{name}}.py
 
+_generate-models-documentation path name:
+    @- just _delete-if-folder-exists "docs/{{name}}"
+    @- just _create-folder-if-not-exists "docs/{{name}}"
+    @- {{GEN_MODELS_DOCUMENTATION}} generate \
+        --input-spec {{path}}/{{name}}-schema.yaml \
+        --generator-name markdown \
+        --output "docs/{{name}}"
+    @- just _clean-all-files .openapi-generator*
+    @- just _clean-all-folders .openapi-generator*
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # TARGETS
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,12 +79,23 @@ build: _build-requirements _build-skip-requirements
 _build-skip-requirements: build-models
 _build-requirements:
     @{{PYTHON}} -m pip install --disable-pip-version-check -r requirements.txt
-build-models: _check-system-requirements _build-models-nochecks
-_build-models-nochecks:
+build-models:
+    @just _check-system-requirements
+    @just _build-models
+    @just _build-models-documentation
+_build-models:
     @echo "Generate data models from schemata."
+    @just _delete-if-folder-exists "models/generated"
     @just _create-folder-if-not-exists "models/generated"
     @- just _generate-models "models" "config"
     @- just _generate-models "models" "commands"
+_build-models-documentation:
+    @echo "Generate documentations data models from schemata."
+    @just _delete-if-folder-exists "docs"
+    @just _create-folder-if-not-exists "docs"
+    @- just _generate-models-documentation "models" "config"
+    @- just _generate-models-documentation "models" "commands"
+
 
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # TARGETS: run
@@ -172,3 +194,7 @@ _check-system-requirements:
         echo "Command '{{GEN_MODELS}}' did not work. Ensure that the installation of 'datamodel-code-generator' worked and that system paths are set." \
         exit 1; \
     fi
+    @if ! ( {{GEN_MODELS_DOCUMENTATION}} --help >> /dev/null 2> /dev/null ); then \
+        echo "Command '{{GEN_MODELS_DOCUMENTATION}}' did not work. Ensure that the installation of 'datamodel-code-generator' worked and that system paths are set." \
+        exit 1; \
+    fi

code/python/requirements.txt

@@ -23,6 +23,7 @@ lazy-load>=0.8.2
 pyyaml>=6.0
 pydantic>=1.9.0
 datamodel-code-generator>=0.13.0
+openapi-generator-cli>=4.3.1
 
 # misc
 lorem>=0.1.1