✨ Add commands to generate scopes.md and kanalen.md docs

issue: VNG-Realisatie/gemma-zaken#1706

bin/generate_schema

@@ -31,3 +31,9 @@ src/manage.py generate_swagger \
     --mock-request \
     --url https://example.com/api/v1 \
     --to-markdown-table
+
+echo "Generating scopes.md"
+src/manage.py generate_scopes --output-file ./src/scopes.md
+
+echo "Generating kanalen.md"
+src/manage.py generate_kanalen --output-file ./src/kanalen.md

bin/generate_schema.cmd

@@ -29,3 +29,9 @@ python src\manage.py generate_swagger^
     --mock-request^
     --url https://example.com/api/v1^
     --to-markdown-table
+
+echo "Generating scopes.md"
+src\manage.py generate_scopes --output-file ./src/scopes.md
+
+echo "Generating kanalen.md"
+src\manage.py generate_kanalen --output-file ./src/kanalen.md

vng_api_common/management/commands/generate_kanalen.py

@@ -0,0 +1,40 @@
+import logging
+import os
+
+from django.conf import settings
+from django.core.management import BaseCommand
+from django.template.loader import render_to_string
+
+from ...notifications.kanalen import KANAAL_REGISTRY
+
+
+class Command(BaseCommand):
+    """
+    Generate a markdown file documenting the notification channels of the component
+    """
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+
+        parser.add_argument(
+            "--output-file",
+            dest="output_file",
+            default=None,
+            help="Name of the output file",
+        )
+
+    def handle(self, output_file, *args, **options):
+        kanalen = sorted(KANAAL_REGISTRY, key=lambda s: s.label)
+
+        template = "vng_api_common/kanalen.md"
+        markdown = render_to_string(
+            template,
+            context={
+                "kanalen": kanalen,
+                "project_name": settings.PROJECT_NAME,
+                "site_title": settings.SITE_TITLE,
+            },
+        )
+
+        with open(output_file, "w") as f:
+            f.write(markdown)

vng_api_common/management/commands/generate_scopes.py

@@ -0,0 +1,43 @@
+import logging
+import os
+
+from django.conf import settings
+from django.core.management import BaseCommand
+from django.template.loader import render_to_string
+
+from ...scopes import SCOPE_REGISTRY
+
+
+class Command(BaseCommand):
+    """
+    Generate a markdown file documenting the auth scopes of the component
+    """
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+
+        parser.add_argument(
+            "--output-file",
+            dest="output_file",
+            default=None,
+            help="Name of the output file",
+        )
+
+    def handle(self, output_file, *args, **options):
+        scopes = sorted(
+            (scope for scope in SCOPE_REGISTRY if not scope.children),
+            key=lambda s: s.label,
+        )
+
+        template = "vng_api_common/scopes.md"
+        markdown = render_to_string(
+            template,
+            context={
+                "scopes": scopes,
+                "project_name": settings.PROJECT_NAME,
+                "site_title": settings.SITE_TITLE,
+            },
+        )
+
+        with open(output_file, "w") as f:
+            f.write(markdown)

vng_api_common/templates/vng_api_common/kanalen.md

@@ -0,0 +1,24 @@
+# {{ project_name }}
+## {{ site_title }}
+
+Kanalen worden typisch per component gedefinieerd. Producers versturen berichten op bepaalde kanalen,
+consumers ontvangen deze. Consumers abonneren zich via een notificatiecomponent (zoals {{ 'https://notificaties-api.vng.cloud/api/v1/schema/'|urlize }}) op berichten.
+
+Hieronder staan de kanalen beschreven die door deze component gebruikt worden, met de kenmerken bij elk bericht.
+
+De architectuur van de notificaties staat beschreven op {{ 'https://zaakgerichtwerken.vng.cloud/themas/achtergronddocumentatie/notificaties'|urlize }}.
+
+{% for kanaal in kanalen %}
+### {{ kanaal.label }}
+
+**Kanaal**
+`{{ kanaal.label }}`
+
+{{ kanaal.description|default:""|urlize }}
+
+**Resources en acties**
+
+{% for resource, actions in kanaal.get_usage %}
+* <code>{{ resource }}</code>: {{ actions|join:", " }}
+{% endfor %}
+{% endfor %}

vng_api_common/templates/vng_api_common/scopes.md

@@ -0,0 +1,15 @@
+{% load vng_api_common markup_tags %}
+# {{ project_name }} scopes
+## {{ site_title }}
+
+Scopes worden typisch per component gedefinieerd en geven aan welke rechten er zijn.
+Het JWT van de aanroepende component geeft aan welke rechten deze component heeft of wil verkrijgen.
+
+{% for scope in scopes %}
+### {{ scope.label }}
+
+**Scope**
+`{{ scope.label }}`
+
+{{ scope.description|default:"" }}
+{% endfor %}