cal-docs-server 3.0.0b1__py3-none-any.whl

cal_docs_server/render_index.py

@@ -0,0 +1,174 @@
+# ----------------------------------------------------------------------------------------
+#   render_index
+#   ------------
+#
+#   Renders the `IndexList` produced in `index_docs.make_index` into an HTML page
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena
+#
+#   Version History
+#   ---------------
+#   Mar 2024 - Created
+#   Dec 2025 - New version 2
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import importlib.resources
+import os
+import string
+from typing import TYPE_CHECKING
+from . import async_file
+from . import index_docs
+
+if TYPE_CHECKING:
+    from .index_docs import IndexItemDict
+    from .index_docs import IndexList
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+g_template_file: str | None = None
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def render_index(
+    root_directory: str, server_name: str = "Documents Server"
+) -> str:
+    """
+    Builds index from `root_directory` and renders it into HTML
+    """
+
+    index_list: IndexList = await index_docs.make_index(root_directory=root_directory)
+    return await render_index_from_list(index_list, server_name)
+
+
+# ----------------------------------------------------------------------------------------
+async def render_index_from_list(
+    index_list: IndexList, server_name: str = "Documents Server"
+) -> str:
+    """
+    Renders an already-built index list into HTML
+    """
+    template: str = await _get_template()
+
+    content = await _create_generated_content(index_list)
+    template_subs = {"INSERT_DATA": content, "SERVER_NAME": server_name}
+    html = string.Template(template).substitute(template_subs)
+
+    return html
+
+
+# ----------------------------------------------------------------------------------------
+#   Private Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def _get_template() -> str:
+    """
+    Reads the template HTML file. It is stored as a resource within the server.
+    Caches it so it only reads once.
+    """
+    global g_template_file
+
+    if not g_template_file:
+        file_folder = importlib.resources.files("cal_docs_server.resources")
+        file_path: str = os.path.join(str(file_folder), "index_template.html")
+        async with async_file.open_text(file_path, "rt") as f:
+            g_template_file = await f.read()
+    return g_template_file
+
+
+# ----------------------------------------------------------------------------------------
+async def _create_generated_content(index_list: IndexList) -> str:
+    """
+    Takes the json string of the scan and produces the html content from it. This does not
+    include the template this is the "middle" section that gets inserted into the template
+    """
+
+    text: str = ""
+    index_item: IndexItemDict
+    for index_item in index_list:
+        item_text = await _single_item_content(index_item)
+        text += item_text
+    return text
+
+
+# ----------------------------------------------------------------------------------------
+async def _single_item_content(index_item: IndexItemDict) -> str:
+    """
+    Generates the HTML for a specific index item
+    """
+
+    # Build the card HTML
+    text = '<div class="doc-card">\n'
+    text += '  <div class="doc-header">\n'
+
+    # Add logo if available
+    if logo_ref := index_item["logo_ref"]:
+        text += (
+            f'    <img src="{logo_ref}" class="doc-logo" alt="{index_item["name"]}'
+            ' logo">\n'
+        )
+
+    # Add title
+    text += '    <div class="doc-title">\n'
+    # Always use the unversioned directory_name for the link
+    text += (
+        "      <h3><a"
+        f' href="{index_item["directory_name"]}">{index_item["name"]}</a></h3>\n'
+    )
+    text += "    </div>\n"
+    text += "  </div>\n"
+
+    # Add description if available
+    if index_item["description"]:
+        text += f'  <div class="doc-description">{index_item["description"]}</div>\n'
+
+    # Add version links
+    text += '  <div class="doc-versions">\n'
+    # Always use the unversioned directory_name for the "Latest" link
+    text += (
+        f'    <a href="{index_item["directory_name"]}" class="version-link'
+        ' latest">Latest</a>\n'
+    )
+
+    if index_item["versions"]:
+        version_count = len(index_item["versions"])
+        version_text = f"{version_count} version" + ("s" if version_count != 1 else "")
+
+        text += f"""    <button class="versions-toggle">
+      <span class="version-count">{version_text}</span>
+      <svg fill="currentColor" viewBox="0 0 20 20">
+        <path fill-rule="evenodd" d="M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z" clip-rule="evenodd"/>
+      </svg>
+    </button>
+  </div>
+  <div class="versions-list">
+"""
+        for version in index_item["versions"]:
+            text += (
+                f'    <a href="{version["directory_name"]}"'
+                f' class="version-link">{version["version"]}</a>\n'
+            )
+        text += "  </div>\n"
+    else:
+        text += "  </div>\n"
+
+    text += "</div>\n"
+
+    return text

cal_docs_server/render_md.py

@@ -0,0 +1,90 @@
+# ----------------------------------------------------------------------------------------
+#   render_md
+#   ---------
+#
+#   Renders a MarkDown file into HTML
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena
+#
+#   Version History
+#   ---------------
+#   Mar 2024 - Created
+#   Dec 2025 - New version 2
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import asyncio
+import importlib.resources
+import os
+import string
+import markdown
+from . import async_file
+
+# ----------------------------------------------------------------------------------------
+#   Globals
+# ----------------------------------------------------------------------------------------
+
+g_md_template: str | None = None
+"""Cache the template file"""
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def md_to_html(md: bytes) -> bytes:
+    """
+    Converts the MarkDown file data to html and returns it.
+    """
+
+    contents_html: str = await _async_md_convert(md)
+
+    template = await _get_template()
+    template_subs = {"INSERT_DATA": contents_html}
+    html = string.Template(template).substitute(template_subs)
+
+    return html.encode()
+
+
+# ----------------------------------------------------------------------------------------
+#   Private Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def _get_template() -> str:
+    """
+    Reads the template HTML file. It is stored as a resource within the server.
+    """
+
+    global g_md_template
+
+    if not g_md_template:
+        file_folder = importlib.resources.files("cal_docs_server.resources")
+        file_path: str = os.path.join(str(file_folder), "md_template.html")
+        async with async_file.open_text(file_path, "rt") as f:
+            file_contents = await f.read()
+        g_md_template = file_contents
+
+    return g_md_template
+
+
+# ----------------------------------------------------------------------------------------
+async def _async_md_convert(md: bytes) -> str:
+    """
+    Wraps markdown.markdown in a thread,
+    """
+
+    md_text = md.decode(errors="replace")
+    html = await asyncio.to_thread(markdown.markdown, md_text, extensions=["extra"])
+    return html

cal_docs_server/resources/__init__.py

@@ -0,0 +1 @@
+

cal_docs_server/resources/help.md

@@ -0,0 +1,171 @@
+# Documentation Server Help
+
+The CAL Documentation Server provides a central location to store project documentation
+with automatic indexing and support for versioned documentation.
+
+Anyone can easily add their documentation by choosing a unique project name.
+
+## Supported Documentation Types
+
+The documentation server supports:
+
+- **Static HTML sites** - Pre-built HTML documentation (e.g., from Sphinx, MkDocs, pdoc)
+- **Markdown files** - `.md` files rendered on-the-fly with syntax highlighting
+- **Mixed content** - Combination of HTML and markdown files
+
+### Requirements
+
+Documentation must be self-contained in a directory with either `index.html` or `index.md`
+at the root.
+
+## Configuration with docinfo
+
+Add a `docinfo` file to your documentation root to customize how it appears in the index.
+
+**Supported formats:** `docinfo.json`, `docinfo.json5`, `docinfo.yaml`, `docinfo.yml`
+
+**Available fields:**
+
+- `name` - Display name shown in index (defaults to directory name)
+- `description` - Description text shown under the project name
+- `noindex` - Set to `true` to hide from index (still accessible via direct URL)
+
+**Logo support:**
+
+Place an image file named `docinfo.png`, `docinfo.jpg`, or `docinfo.svg` in the same
+directory to display a logo on the index page.
+
+**Example docinfo.json:**
+
+```json
+{
+  "name": "My Project",
+  "description": "A comprehensive guide to using My Project",
+  "noindex": false
+}
+```
+
+## Version Management
+
+The server supports versioned documentation with automatic "Latest" link handling.
+
+### Directory Naming Convention
+
+- **Unversioned:** `my-project/` (optional, can be omitted if only versioned dirs exist)
+- **Versioned:** `my-project-1.2.3/`, `my-project-2.0.0/`, etc.
+
+The server automatically:
+
+- Detects all versions based on directory names (e.g., `my-project-*`)
+- Filters out beta/alpha/rc versions when determining "Latest"
+- Redirects the unversioned URL (`/my-project/`) to the latest stable version
+- Sorts versions using semantic versioning
+
+**Example directory structure:**
+
+```
+docs/
+├── my-project-1.0.0/
+├── my-project-2.0.0/
+├── my-project-2.1.0/
+└── my-project-3.0.0b1/    (excluded from "Latest")
+```
+
+In this example, accessing `/my-project/` serves content from `my-project-2.1.0/` (the
+latest non-beta version).
+
+## REST API
+
+The server provides a REST API for programmatic access to documentation.
+
+### cal-docs-client
+
+For command-line access to the API, use the `cal-docs-client` tool:
+
+```bash
+# Install the client
+pip install cal-docs-client
+
+# List projects
+cal-docs-client list
+
+# Upload documentation
+cal-docs-client upload my-project-1.0.0-docs.zip
+```
+
+See the [cal-docs-client documentation](https://example.com/) for full usage.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/version` | Returns product name and version |
+| GET | `/api/spec` | Returns OpenAPI 3.0 specification |
+| GET | `/api/projects` | Lists all projects and versions |
+| GET | `/api/projects?search=term` | Filter projects by name |
+| GET | `/api/download/{project}/{version}` | Download project as zip |
+| POST | `/api/upload` | Upload documentation (requires auth) |
+
+### Authentication
+
+Upload requires token authentication via the `X-Token` header. Contact your administrator
+to obtain a token.
+
+```
+X-Token: your-secret-token
+```
+
+### Examples
+
+```bash
+# List all projects
+curl http://example.com/api/projects
+
+# Search projects
+curl "http://example.com/api/projects?search=my-project"
+
+# Download latest version as zip
+curl -o docs.zip http://example.com/api/download/my-project/latest
+
+# Download specific version
+curl -o docs.zip http://example.com/api/download/my-project/1.2.3
+
+# Upload documentation (requires token)
+curl -X POST -H "X-Token: your-token" \
+     -F "file=@my-project-1.0.0-docs.zip" \
+     http://example.com/api/upload
+```
+
+## Uploading Documentation
+
+### Zip File Naming
+
+When uploading via the API, name your zip file to indicate the project and version:
+
+- `my-project-1.2.3.zip`
+- `my-project-1.2.3-docs.zip`
+
+The server extracts the project name and version from the filename.
+
+### Using GitLab CI
+
+Upload documentation automatically as part of your CI/CD pipeline:
+
+```yaml
+upload_docs:
+  stage: deploy
+  only:
+    - tags
+  script:
+    - zip -r my-project-${CI_COMMIT_TAG}-docs.zip ./html
+    - curl -X POST -H "X-Token: ${DOC_SERVER_TOKEN}" \
+           -F "file=@my-project-${CI_COMMIT_TAG}-docs.zip" \
+           "${DOC_SERVER_URL}/api/upload"
+```
+
+## Tips
+
+- Only upload docs from tagged releases or manual jobs, not every commit
+- Use semantic versioning for directory names (e.g., `1.2.3`, not `v1.2.3`)
+- Beta/alpha versions should include the suffix (e.g., `2.0.0b1`, `3.0.0-alpha`)
+- The server caches the index for 20 seconds, so changes may take a moment to appear