Docs: init redoc internal rest inspired docs

docs/.gitignore

@@ -1,4 +1,5 @@
 /site/reference
 /site/static
 /site/options-page
+/site/openapi.json
 !/site/static/extra.css

docs/mkdocs.yml

@@ -181,6 +181,9 @@ nav:
           - 05-deployment-parameters: decisions/05-deployment-parameters.md
           - Template: decisions/_template.md
   - Options: options.md
+  - Developer:
+      - Introduction: intern/index.md
+      - API: intern/api.md
 
 docs_dir: site
 site_dir: out
@@ -238,3 +241,4 @@ extra:
 plugins:
   - search
   - macros
+  - redoc-tag

docs/nix/default.nix

@@ -3,6 +3,7 @@
   pkgs,
   module-docs,
   clan-cli-docs,
+  clan-lib-openapi,
   asciinema-player-js,
   asciinema-player-css,
   roboto,
@@ -29,6 +30,7 @@ pkgs.stdenv.mkDerivation {
       mkdocs
       mkdocs-material
       mkdocs-macros
+      mkdocs-redoc-tag
     ]);
   configurePhase = ''
     pushd docs
@@ -36,6 +38,10 @@ pkgs.stdenv.mkDerivation {
     mkdir -p ./site/reference/cli
     cp -af ${module-docs}/* ./site/reference/
     cp -af ${clan-cli-docs}/* ./site/reference/cli/
+
+    mkdir -p ./site/reference/internal
+    cp -af ${clan-lib-openapi} ./site/openapi.json
+
     chmod -R +w ./site/reference
     echo "Generated API documentation in './site/reference/' "
 

docs/nix/flake-module.nix

@@ -127,7 +127,12 @@
       packages = {
         docs = pkgs.python3.pkgs.callPackage ./default.nix {
           clan-core = self;
-          inherit (self'.packages) clan-cli-docs docs-options inventory-api-docs;
+          inherit (self'.packages)
+            clan-cli-docs
+            docs-options
+            inventory-api-docs
+            clan-lib-openapi
+            ;
           inherit (inputs) nixpkgs;
           inherit module-docs;
           inherit asciinema-player-js;

docs/site/intern/api.md

@@ -0,0 +1,7 @@
+---
+template: options.html
+hide:
+  - navigation
+  - toc
+---
+<redoc src="/openapi.json" />

docs/site/intern/index.md

@@ -0,0 +1,25 @@
+# Developer Documentation
+
+!!! Danger
+    This documentation is **not** intended for external users. It may contain low-level details and internal-only interfaces.*
+
+Welcome to the internal developer documentation.
+
+This section is intended for contributors, engineers, and internal stakeholders working directly with our system, tooling, and APIs. It provides a technical overview of core components, internal APIs, conventions, and patterns that support the platform.
+
+Our goal is to make the internal workings of the system **transparent, discoverable, and consistent** — helping you contribute confidently, troubleshoot effectively, and build faster.
+
+## What's Here?
+
+!!! note "docs migration ongoing"
+
+- [ ] **API Reference**: 🚧🚧🚧 Detailed documentation of internal API functions, inputs, and expected outputs. 🚧🚧🚧
+- [ ] **System Concepts**: Architectural overviews and domain-specific guides.
+- [ ] **Development Guides**: How to test, extend, or integrate with key components.
+- [ ] **Design Notes**: Rationales behind major design decisions or patterns.
+
+## Who is This For?
+
+* Developers contributing to the platform
+* Engineers debugging or extending internal systems
+* Anyone needing to understand **how** and **why** things work under the hood

pkgs/clan-cli/open_api.py

@@ -54,7 +54,7 @@ def normalize_tag(parts: list[str]) -> list[str]:
 
 
 def operation_to_tag(op_name: str) -> str:
-    def check_operation_name(verb: str, resource_nouns: list[str]):
+    def check_operation_name(verb: str, _resource_nouns: list[str]) -> None:
         if not is_verb(verb):
             print(
                 f"""⚠️ WARNING: Verb '{op_name}' of API operation {op_name} is not allowed.
@@ -65,7 +65,7 @@ Use one of: {", ".join(COMMON_VERBS)}
     parts = op_name.lower().split("_")
     normalized = normalize_tag(parts)
 
-    check_operation_name(verb=normalized[0], resource_nouns=normalized[1:])
+    check_operation_name(normalized[0], normalized[1:])
 
     return " / ".join(normalized[1:])
 
@@ -113,10 +113,10 @@ def make_schema_name(func_name: str, part: str) -> str:
 
 
 def main() -> None:
-    INPUT_PATH = Path(os.environ["INPUT_PATH"])
+    input_path = Path(os.environ["INPUT_PATH"])
 
     # === Load input JSON Schema ===
-    with INPUT_PATH.open() as f:
+    with input_path.open() as f:
         schema = json.load(f)
 
     defs = schema.get("$defs", {})
@@ -126,9 +126,9 @@ def main() -> None:
     openapi = {
         "openapi": "3.0.3",
         "info": {
-            "title": "Function-Based API",
+            "title": "Function-Based Python API",
             "version": "1.0.0",
-            "description": "Auto-generated OpenAPI 3.0 spec from custom JSON Schema",
+            "description": "!!! INTERNAL USE ONLY !!! We don't provide a world usable API yet.\nThis prototype maps python function calls to POST Requests because we are planning towards RESTfull API in the future.",
         },
         "paths": {},
         "components": {"schemas": {}},
@@ -142,11 +142,11 @@ def main() -> None:
         # Register schemas under components
         args_name = make_schema_name(func_name, "args")
         return_name = make_schema_name(func_name, "return")
-        openapi["components"]["schemas"][args_name] = args_schema
+        openapi["components"]["schemas"][args_name] = args_schema  # type: ignore
-        openapi["components"]["schemas"][return_name] = return_schema
+        openapi["components"]["schemas"][return_name] = return_schema  # type: ignore
         tag = operation_to_tag(func_name)
         # Create a POST endpoint for the function
-        openapi["paths"][f"/{func_name}"] = {
+        openapi["paths"][f"/{func_name}"] = {  # type: ignore
             "post": {
                 "summary": func_name,
                 "operationId": func_name,
@@ -178,7 +178,7 @@ def main() -> None:
     for def_name, def_schema in defs.items():
         fixed_schema = fix_nullables(deepcopy(def_schema))
         fix_error_refs(fixed_schema)
-        openapi["components"]["schemas"][def_name] = fixed_schema
+        openapi["components"]["schemas"][def_name] = fixed_schema  # type: ignore
 
     # === Write to output JSON ===
     with Path("openapi.json").open("w") as f: