Update documentation with API for liberty

Author: fblettner

.DS_Store

@@ -0,0 +1,86 @@
+import os
+from playwright.sync_api import sync_playwright
+import json
+
+BASE_URL = "http://docs.nomana-it.fr"
+OUTPUT_FILE = "liberty_documentation.json"
+
+NAV = [
+    {"title": "Getting Started", "path": "liberty/getting-started.md", "description": "Learn the basics of Liberty Framework."},
+    {"title": "Release Notes", "path": "liberty/release-notes.md", "description": "See what's new in the latest release."},
+    {
+        "title": "Installation",
+        "description": "Step-by-step installation guides.",
+        "children": [
+            {"title": "Architecture", "path": "liberty/technical/architecture.md", "description": "Understand the architecture of Liberty Framework."},
+            {"title": "Docker Installation Guide", "path": "liberty/technical/installation.md", "description": "Set up Liberty Framework using Docker."},
+            {"title": "Installation Tools Deployment Guide", "path": "liberty/technical/tools-deployment.md", "description": "Learn about tools for deploying Liberty Framework."},
+            {"title": "Liberty Deployment Guide", "path": "liberty/technical/liberty-deployment.md", "description": "Guide to deploying Liberty Framework."},
+            {"title": "Create Linux Services", "path": "liberty/technical/linux-services.md", "description": "Create Linux services for Liberty Framework."},
+            {"title": "Enable SSL with Traefik", "path": "liberty/technical/post-ssl.md", "description": "Enable SSL using Traefik for enhanced security."},
+        ]
+    },
+    {
+        "title": "Nomasx-1",
+        "description": "Guides and settings for Nomasx-1.",
+        "children": [
+            {
+                "title": "Administrator's Guide",
+                "description": "Administrator resources and tools.",
+                "children": [
+                    {"title": "Global Settings", "path": "liberty/nomasx1/admin/global-settings.md", "description": "Manage global settings for Nomasx-1."},
+                ]
+            }
+        ]
+    }
+]
+
+def flatten_nav(nav, parent_title=""):
+    """Flatten the navigation into a list of titles and paths."""
+    pages = []
+    for item in nav:
+        title = f"{parent_title} > {item['title']}" if parent_title else item['title']
+        if "path" in item:
+            pages.append({"title": title, "path": item["path"]})
+        if "children" in item:
+            pages.extend(flatten_nav(item["children"], title))
+    return pages
+
+def extract_page_content(page, url):
+    """Extract the main content from a MkDocs Material page."""
+    page.goto(url, wait_until="networkidle")
+    content = page.locator("main").inner_text()  # Main content selector for MkDocs Material
+    return content.strip()
+
+def generate_documentation_json(base_url, nav):
+    """Generate a JSON file with all documentation content."""
+    pages = flatten_nav(nav)
+    documentation = []
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        context = browser.new_context()
+
+        for page_info in pages:
+            title = page_info["title"]
+            path = page_info["path"]
+            url = f"{base_url}/{path.replace('.md', '').strip('/')}"
+
+            try:
+                page = context.new_page()
+                content = extract_page_content(page, url)
+                documentation.append({"title": title, "url": url, "content": content})
+                print(f"Extracted content for {title}")
+            except Exception as e:
+                print(f"Failed to extract content for {title}: {e}")
+                continue
+
+        browser.close()
+
+    # Save to a JSON file
+    with open(OUTPUT_FILE, "w", encoding="utf-8") as f:
+        json.dump(documentation, f, indent=2, ensure_ascii=False)
+    print(f"Documentation saved to {OUTPUT_FILE}")
+
+if __name__ == "__main__":
+    generate_documentation_json(BASE_URL, NAV)

docs/liberty/api/liberty-api.md

@@ -32,6 +32,7 @@ theme:
     - navigation.top
     - navigation.footer
     - header.autohide
+    - content.tooltips
 nav:
   - Home: index.md
   - Liberty:
@@ -45,7 +46,8 @@ nav:
         - Enable SSL with Traefik: liberty/technical/post-ssl.md
       - Nomasx-1:
           - Administrator's Guide: 
-            - Global Settings: liberty/nomasx1/admin/global-settings.md       
+            - Global Settings: liberty/nomasx1/admin/global-settings.md   
+      - API Documentation: liberty/api/liberty-api.md
       - Release Notes: liberty/release-notes.md
       - Issues: liberty/issues.md
       - Incidents: liberty/incidents.md        
@@ -62,7 +64,7 @@ nav:
 plugins:
   - search
   - awesome-pages
-  - minify
+  - minify  
   - blog:
       blog_toc: true
 extra:
@@ -95,6 +97,10 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
+  - admonition
+  - pymdownx.details
+  - pymdownx.tabbed:
+      alternate_style: true
 extra_css:
   - css/custom.css
 extra_javascript:

json/liberty-api.json

@@ -0,0 +1,105 @@
+import json
+from collections import defaultdict
+
+# Load the OpenAPI JSON
+with open("../json/liberty-api.json", "r") as f:
+    openapi_data = json.load(f)
+
+# Add background color for method
+def method_with_style(method):
+    color_map = {
+        "GET": "green",    # Light green
+        "POST": "blue",    # Light blue
+        "PUT": "purple",   # Light purple
+        "DELETE": "red",   # Light red
+    }
+    color = color_map.get(method.upper(), "inherit")  # Default to inherit color
+    return f'<span style="background:{color}; font-size: 16px; padding-left: 10px; padding-right: 10px">{method.upper()}</span>'
+
+
+# Initialize Markdown content
+markdown = f"# {openapi_data['info']['title']}\n\n"
+markdown += f"**Description:** {openapi_data['info']['description']}\n\n"
+markdown += f"**Version:** {openapi_data['info']['version']}\n\n"
+
+method_order = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]
+
+# Sort paths and methods
+paths = openapi_data["paths"]
+
+# Group paths by tags
+tagged_paths = defaultdict(list)
+for path, methods in paths.items():
+    for method, details in methods.items():
+        tags = details.get("tags", ["Untagged"])  # Use "Untagged" if no tags are provided
+        for tag in tags:
+            tagged_paths[tag].append((path, method, details))
+
+# Iterate through tags and their respective paths
+for tag, endpoints in tagged_paths.items():
+    markdown += f"## {tag}\n\n"  # Add tag as a section header
+
+    # Sort endpoints by their method order and path
+    endpoints = sorted(
+        endpoints,
+        key=lambda x: (method_order.index(x[1].upper()) if x[1].upper() in method_order else len(method_order), x[0])
+    )
+
+    for path, method, details in endpoints:
+        method_with_bg = method_with_style(method)
+        markdown += f"### {details.get('summary', 'No summary available')}\n\n"
+        markdown += f"{details.get('description', 'No description available.')}\n\n"
+        markdown += f"{method_with_bg} **`{path}`**\n\n"
+
+        # Parameters Section
+        markdown += "!!! abstract \"Query Parameters\"\n"
+        if "parameters" in details:
+            for param in details["parameters"]:
+                required = " (**Required**)" if param.get("required", False) else ""
+                default = f" *(Default: `{param['schema']['default']}`)*" if "default" in param["schema"] else ""
+                markdown += f"    - **`{param['name']}`** *(in {param['in']})*: {param.get('description', 'No description')}{required}{default}\n"
+        else:
+            markdown += "    - **None**\n\n"
+
+        # Request Body Section
+        if "requestBody" in details:
+            markdown += "!!! abstract \"Request Body\"\n"
+            request_body = details["requestBody"]["content"]
+            for content_type, body_details in request_body.items():
+                markdown += f"    - **Content-Type:** `{content_type}`\n"
+                body_json = json.dumps(body_details.get('schema', {}), indent=4)
+                json_block = "\n".join([f"        {line}" for line in body_json.splitlines()])
+                markdown += f"      - **Example:**\n\n"
+                markdown += f"        ```json\n{json_block}\n        ```\n"
+
+        # Responses Section
+        markdown += "**📥 Responses:**\n\n"
+        for status, response in details["responses"].items():
+            # Determine the type of admonition based on the status code
+            if str(status).startswith("2"):
+                admonition_type = "success"
+            elif str(status).startswith("4"):
+                admonition_type = "warning"
+            elif str(status).startswith("5"):
+                admonition_type = "danger"
+            else:
+                admonition_type = "note"  # Default to 'note' for other status codes
+            markdown += f"??? {admonition_type} \"Response `{status}`: {response.get('description', 'No description available.')}\"\n"
+            if "content" in response:
+                for content_type, content_details in response["content"].items():
+                    markdown += f"    - **Content-Type:** `{content_type}`\n"
+                    if "example" in content_details:
+                        example_json = json.dumps(content_details["example"], indent=4)
+                        # Ensure the JSON block is properly indented
+                        json_block = "\n".join([f"        {line}" for line in example_json.splitlines()])
+                        markdown += f"      - **Example:**\n\n"
+                        markdown += f"        ```json\n{json_block}\n        ```\n"
+
+        markdown += "\n---\n\n"
+
+
+# Save to a Markdown file for MkDocs
+with open("../docs/liberty/api/liberty-api.md", "w") as f:
+    f.write(markdown)
+
+print("API documentation exported to docs/liberty/api/liberty-api.md!")

json/liberty_documentation.json

@@ -19,3 +19,4 @@
     padding: 12px 20px;  /* Spacious padding */
     border-radius: 6px;  /* Slightly rounded corners */
 }
+