DOC: mkdocs migration

bin/docs

@@ -1,31 +1,21 @@
 #!/bin/bash
 
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-cd "$DIR/../docs/api"
+cd "$DIR/.."
+zon_mkdocs_image="europe-west3-docker.pkg.dev/zeitonline-engineering/docker-zon/zon-mkdocs:latest"
 
-if [[ package-lock.json -nt .npm.success ]]; then
-    npm install
-    touch .npm.success
-fi
+docker pull $zon_mkdocs_image
 
-cd "$DIR/../docs"
 COMMAND=${1:-html}
 case $COMMAND in
-    html)
-        docker run --rm \
-          -v $(pwd)/:/docs/ \
-          europe-west3-docker.pkg.dev/zeitonline-engineering/docker-zon/sphinx-zon:latest \
-          sphinx-build -j auto -a -b html . ./htdocs
-    ;;
     serve)
-        docker run --rm \
-          -v $(pwd)/:/docs/ \
-          -p 8000:8000 \
-          europe-west3-docker.pkg.dev/zeitonline-engineering/docker-zon/sphinx-zon:latest \
-          sphinx-autobuild --host 0.0.0.0 -j auto -a -b html . ./htdocs
+        docker run --rm -it -p 8000:8000 -v ${PWD}:/docs $zon_mkdocs_image
+    ;;
+    html)
+        docker run --rm -v ${PWD}:/docs $zon_mkdocs_image build --site-dir public
     ;;
     *)
         echo "Unrecognized command: $COMMAND"
         exit 1
     ;;
-esac
+esac

docs/api.md

@@ -0,0 +1 @@
+<swagger-ui src="https://zappi.staging.zeit.de/1.0.0/openapi.yaml"/>

docs/codingstyle.md

@@ -0,0 +1,20 @@
+# YAML Coding-Style
+
+## Syntax
+
+-   Indentation: 2 Leerzeichen (Listen immer einrücken, auch wenn der
+    yaml-Standard es dort nicht zwingend verlangt)
+-   Strings quoten mit Double Quotes (`"foobar"`, NICHT `'foobar'`)
+-   Identifier nicht quoten (`type: string`, NICHT `type: "string"`)
+-   Leerzeilen zwischen inhaltlichen Abschnitten verwenden
+-   Inline Listen/Dicts höchstens bei Beispielen verwenden (z.B.
+    `example: ["zplus"]`), sonst immer neue Zeile und einrücken
+
+## Namen
+
+-   Schema-Objekte verwenden CamelCase mit Großbuchstaben vorn (z.B.
+    `CenterpageElement`, `TabDefinitionBase`)
+-   Properties verwenden dromedaryCase (lower camel case) (z.B.
+    `baseUrl`, `dateFirstPublished`)
+-   Identifier verwenden kebab-case und werden klein geschrieben (z.B.
+    `zplus-register`, `menu-entry-native`)

docs/index.md

@@ -0,0 +1,8 @@
+# Zappi (ZON-App-API)
+
+- [Überblick](overview.md)
+- [Entwickler-Onboarding](onboarding.md)
+- [YAML Coding-Style](codingstyle.md)
+- [Betriebshandbuch](operations.md)
+- [API Validierung](validation.md)
+- [API](api.md)

docs/onboarding.md

@@ -0,0 +1,38 @@
+# Entwickler-Onboarding
+
+## API-Dokumentation
+
+Die API-Dokumentation wird als OpenAPI-Spezifikation in `api.yaml`
+gepflegt, und mit dem swagger-ui HTML/JS daraus direkt angezeigt.
+
+Wegen CORS&Co muss man lokal immer `bin/docs serve` verwenden.
+
+Die Doku der API findet man lokal unter [http://0.0.0.0:8000/swagger.html](http://0.0.0.0:8000/swagger.html)
+
+## API validieren
+
+Mit `bin/test` kann man die `api.yaml` auf syntaktische Korrektheit mit
+dem OpenAPI-Standard überprüfen.
+
+## Backend
+
+Zappis Backend findet sich in zeit.web.app, dort ist das Zappi Repo als
+Submodule eingebunden.
+
+!!! note
+
+    Das führt mitunter zu Mergekonflikten, wenn verschiedene Versionen des
+    Submodules kollidieren. Hier hilft in vielen Fällen
+    `git submodule update --init --recursive` um das Submodul auf den
+    gegenwärtigen Stand (des Mains) zu bringen.
+
+## Spec Version in zeit.web hochziehen
+
+- in `zeit.web/src/zeit/web/app/spec` auf den main wechseln, main pullen
+- neuen Branch anlegen, Änderung machen, committen, PR stellen, PR mergern
+- auf den Main wechseln, Main pullen -\> neue Änderung sollte da sein
+- in `zeit.web` neuen Branch anlegen
+- `$ git status` sollte zeigen, dass sich `zeit.web/src/zeit/web/app/spec` geändert hat
+- diese Änderung committen und PR in zeit.web stellen
+
+-\> Success

docs/operations.md

@@ -0,0 +1,22 @@
+# Betriebshandbuch
+
+## Deployment
+
+Es gibt GithubActions für das Deployment, die API-SPecification und die
+PRs hier [ZAPPI-Docs](https://github.com/ZeitOnline/docs-zappi/actions/)
+. Diese werden automatisch angestoßen beim Erstellen von PRs bzw beim
+Merge oder Push in den master-Branch.
+
+## Prozesssteuerung
+
+Das Repo ist in zeit.web als submodule eingebunden. Wenn man die
+API-Spezifikation ändern möchte, muss man einen eigenen PR in zeit.web
+stellen und dort das Submodule updaten.
+
+## Monitoring/Observability
+
+-   [Dashboard](https://grafana.ops.zeit.de/d/6pGBoElMz/zappi?orgId=1&from=now-24h&to=now)
+-   [Honeycomb](https://ui.honeycomb.io/zeit-online/datasets/www/result/8EnYuw8S38w)
+    `service.name == fastly.zappi`
+-   [Kibana](https://kibana.ops.zeit.de/app/r/s/GkTB1)
+    `dataview=gke-main-production` und `kubernetes.labels.app == zappi`

docs/overview.md

@@ -0,0 +1,40 @@
+# Überblick
+
+Eine REST API speziell für die aktuell von der Agentur Prepublic
+Entwickelte iOS und Android Anwendung.
+
+## Prototyp der App
+
+Der Prototyp dazu kann auf [Invision](https://invis.io/Z6XKZ4QM3KX)
+eingesehen werden.
+
+## Prototyp des Backends
+
+Die jeweils aktuelle Entwicklungsversion des Backends ist unter
+`https://zappi.staging.zeit.de/x.y.z` erreichbar, wobei `xxx` derzeit
+ein beliebiger Platzhalter für die Version sein kann, der vom Backend
+ignoriert wird. Sprich, egal, welcher Wert dort steht, es wird immer die
+aktuellste Version ausgeliefert.
+
+Der Endpunkt ist per Basic Auth mit hardgecodeten Credentials geschützt,
+die [im Vault
+liegen](https://vault.ops.zeit.de/ui/vault/secrets/zon%2Fv1/show/zappi/production/fastly-basic-auth).
+
+## Versionierung
+
+Bisher ist keine echte Versionierung der API erfolgt, allerdings wird
+die Version in Fastly in den Backend Request Header geschrieben
+`x-zappi-version=major.minor.patch`. Diese Version wird bei
+Requests an die `app_structure` und `app_config`
+Endpunkte genutzt, um unterschiedliche Versionen der Dateien ausliefern
+zu können. Die Dateien liegen in Ordnern in vivi folgen dem Format:
+`/major-minor-patch/{filename}`. Sollte die angefragte Version nicht zur
+Verfügung stehen, wird die `/default-version/{filename}`
+ausgegeben.
+
+## Auslieferung
+
+Zappi liefert Inhalte in Form von json aus, die von der App nativ
+gerendert werden. Das Backend baut hierzu auf dem Framework von
+`zeit.web.site` auf. Aus diesem Grund werden spezielle
+Anpassungen aus den Vertikals nicht unterstützt.

docs/validation.md

@@ -0,0 +1,46 @@
+# API Validierung
+
+Das Schema der API wird sowohl beim Rendern validiert, als auch beim
+Einchecken von Konfiguration im Vivi.
+
+Für genaue Fehlermeldungen bei der Validierung sind die `discriminators`
+im Schema wichtig. Sie machen aus "Validation error in Doc" ein "666
+is not of type String in tabs/0/title". Diese Erweiterung des Schemas
+wurde mit [PR 115](https://github.com/ZeitOnline/docs-zappi/pull/115)
+eingeführt.
+
+## Validierung im Vivi
+
+Beim Einchecken im Vivi werden Dateien vom Typ JSON schon immer darauf
+validiert, dass sie gültiges JSON sind. Das passiert beim Speichern.
+
+Zusätzlich für die großen Structure-Dokumente der API wurde eine weitere
+Validierung beim Einchecken eingeführt. Diese prüft das Dokument gegen
+ein Schema. Beim Bearbeiten von JSON Dokumenten im Vivi gibt es den Tab
+"Validieren". Hier kann eine Schema URL (z.B.
+[https://zappi.staging.zeit.de/1.0.0/openapi.yaml](https://zappi.staging.zeit.de/1.0.0/openapi.yaml)) und ein Schemafeld
+(z.B. `Structure`) eingegeben werden. Dann wird beim Einchecken des
+Dokuments der Inhalt gegen eben jenes Schema überprüft.
+
+Für die meisten JSON Dateien im Vivi gibt es solche eine Validierung
+nicht, da sind diese Felder dann leer. Für API-Strukturen (Navigation
+z.B.) ist das Feld gesetzt. Die Werte werden gespeichert. Also wird
+zukünftig bei jedem Einchecken eines Dokuments gegen das Schema
+validiert.
+
+Achtung: bei einer Schema-Änderung, die zum Beispiel nur auf Staging
+liegt, muss dann auch die Staging-Adresse der Spec eingetragen werden
+(solange diese neue Spec noch nicht nach Production deployed wurde). Die
+wird beim Sync von Production nach Staging ggf überschrieben.
+
+Zur Einordnung: das ist kein Zappi-Feature, sondern in Vivi eingebaut,
+dass man JSON nur als JSON validiert, oder gegen ein konkretes Schema.
+Aber weil das Feature ausschließlich für die Validierung der
+App-Navigation gegen das Zappi-Schema genutzt wird, steht es hier.
+
+## Validierung in der API
+
+Beim Rendern von Inhalten (Centerpages) oder Dokumenten (Navigation
+Structure) über die Zappi (API View bzw. "App-Vertical" von zeit.web)
+wird die Response gegen das Schema validiert, bevor sie gesendet wird.
+Ist etwas falsch, gibt es eine Fehlermeldung im JSON Format als Antwort.