msaas-docs 0.1.0__tar.gz

msaas_docs-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_docs-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-docs
+Version: 0.1.0
+Summary: Knowledge base and documentation system for SaaS products
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'

msaas_docs-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "msaas-docs"
+version = "0.1.0"
+description = "Knowledge base and documentation system for SaaS products"
+requires-python = ">=3.12"
+dependencies = [
+"msaas-api-core",
+"msaas-errors","pydantic>=2.0"
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "httpx>=0.27", "fastapi>=0.110.0", "ruff>=0.8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docs"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_docs-0.1.0/src/docs/__init__.py

@@ -0,0 +1,34 @@
+"""Knowledge base and documentation system for SaaS products."""
+
+from docs.config import DocsConfig, get_docs, init_docs
+from docs.models import (
+    DocCategory,
+    DocPage,
+    DocSearchResult,
+    DocTree,
+    DocVersion,
+    PageStatus,
+)
+from docs.renderer import DocRenderer
+from docs.router import create_docs_router
+from docs.search import DocSearch
+from docs.service import DocsService
+from docs.store import DocsStore, InMemoryStore
+
+__all__ = [
+    "DocCategory",
+    "DocPage",
+    "DocRenderer",
+    "DocSearch",
+    "DocSearchResult",
+    "DocTree",
+    "DocVersion",
+    "DocsConfig",
+    "DocsService",
+    "DocsStore",
+    "InMemoryStore",
+    "PageStatus",
+    "create_docs_router",
+    "get_docs",
+    "init_docs",
+]

msaas_docs-0.1.0/src/docs/config.py

@@ -0,0 +1,51 @@
+"""Global configuration and singleton access for the docs module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docs.service import DocsService
+
+_instance: DocsService | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DocsConfig:
+    """Configuration for the docs module."""
+
+    base_path: str = "/docs"
+    enable_versioning: bool = True
+    enable_search: bool = True
+    default_locale: str = "en"
+    max_versions: int = 100
+    search_snippet_length: int = 160
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+def init_docs(config: DocsConfig | None = None) -> DocsService:
+    """Initialize the global DocsService singleton."""
+    global _instance  # noqa: PLW0603
+    from docs.search import DocSearch
+    from docs.service import DocsService
+    from docs.store import InMemoryStore
+
+    cfg = config or DocsConfig()
+    store = InMemoryStore()
+    search = DocSearch(snippet_length=cfg.search_snippet_length) if cfg.enable_search else None
+    _instance = DocsService(config=cfg, store=store, search=search)
+    return _instance
+
+
+def get_docs() -> DocsService:
+    """Return the global DocsService. Raises if not initialized."""
+    if _instance is None:
+        raise RuntimeError("docs module not initialized -- call init_docs() first")
+    return _instance
+
+
+def reset_docs() -> None:
+    """Reset the global singleton (useful for tests)."""
+    global _instance  # noqa: PLW0603
+    _instance = None

msaas_docs-0.1.0/src/docs/models.py

@@ -0,0 +1,162 @@
+"""Domain models for the docs module."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class PageStatus(StrEnum):
+    """Publication lifecycle status for a documentation page."""
+
+    DRAFT = "draft"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"
+
+
+def _generate_id() -> str:
+    return uuid.uuid4().hex[:16]
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def slugify(text: str) -> str:
+    """Convert text to a URL-friendly slug."""
+    text = text.lower().strip()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    return re.sub(r"-+", "-", text).strip("-")
+
+
+# ---------------------------------------------------------------------------
+# Core models
+# ---------------------------------------------------------------------------
+
+
+class DocCategory(BaseModel):
+    """A category that groups documentation pages."""
+
+    id: str = Field(default_factory=_generate_id)
+    name: str
+    slug: str = ""
+    description: str = ""
+    order: int = 0
+    parent_id: str | None = None
+
+    def model_post_init(self, _context: object) -> None:
+        if not self.slug:
+            self.slug = slugify(self.name)
+
+
+class DocPage(BaseModel):
+    """A single documentation page."""
+
+    id: str = Field(default_factory=_generate_id)
+    slug: str = ""
+    title: str
+    content_markdown: str = ""
+    content_html: str = ""
+    parent_id: str | None = None
+    order: int = 0
+    category: str = ""
+    tags: list[str] = Field(default_factory=list)
+    author_id: str = ""
+    status: PageStatus = PageStatus.DRAFT
+    version: int = 1
+    locale: str = "en"
+    created_at: datetime = Field(default_factory=_now)
+    updated_at: datetime = Field(default_factory=_now)
+    published_at: datetime | None = None
+
+    def model_post_init(self, _context: object) -> None:
+        if not self.slug:
+            self.slug = slugify(self.title)
+
+
+class DocVersion(BaseModel):
+    """An immutable snapshot of a page at a specific version."""
+
+    page_id: str
+    version: int
+    content_markdown: str
+    author_id: str = ""
+    message: str = ""
+    created_at: datetime = Field(default_factory=_now)
+
+
+class DocSearchResult(BaseModel):
+    """A single search hit."""
+
+    page_id: str
+    title: str
+    slug: str
+    snippet: str = ""
+    score: float = 0.0
+    category: str = ""
+
+
+class DocTreeNode(BaseModel):
+    """A node in the navigation tree (page with optional children)."""
+
+    page_id: str
+    title: str
+    slug: str
+    order: int = 0
+    children: list[DocTreeNode] = Field(default_factory=list)
+
+
+class DocTree(BaseModel):
+    """Hierarchical navigation tree, optionally scoped to a category."""
+
+    category: str = ""
+    pages: list[DocTreeNode] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# API request / response helpers
+# ---------------------------------------------------------------------------
+
+
+class CreatePageRequest(BaseModel):
+    title: str
+    content_markdown: str = ""
+    category: str = ""
+    parent_id: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    author_id: str = ""
+    locale: str = "en"
+
+
+class UpdatePageRequest(BaseModel):
+    title: str | None = None
+    content_markdown: str | None = None
+    category: str | None = None
+    parent_id: str | None = None
+    tags: list[str] | None = None
+    order: int | None = None
+    locale: str | None = None
+    version_message: str = ""
+
+
+class RevertRequest(BaseModel):
+    version: int
+
+
+class CreateCategoryRequest(BaseModel):
+    name: str
+    description: str = ""
+    order: int = 0
+    parent_id: str | None = None
+
+
+class PaginatedPages(BaseModel):
+    items: list[DocPage]
+    total: int
+    page: int
+    per_page: int

msaas_docs-0.1.0/src/docs/renderer.py

@@ -0,0 +1,247 @@
+"""Markdown-to-HTML renderer and HTML utilities.
+
+Provides a lightweight, dependency-free renderer covering the most common
+Markdown constructs: headings, paragraphs, bold, italic, inline code,
+code blocks, links, images, unordered/ordered lists, blockquotes,
+horizontal rules, and tables.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TocEntry:
+    """A single heading in a table of contents."""
+
+    level: int
+    text: str
+    anchor: str
+
+
+@dataclass
+class DocRenderer:
+    """Stateless Markdown renderer with TOC/text extraction helpers."""
+
+    heading_prefix: str = "doc-"
+    _anchor_counts: dict[str, int] = field(default_factory=dict, repr=False)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render_markdown(self, content: str) -> str:
+        """Convert Markdown text to HTML."""
+        self._anchor_counts = {}
+        lines = content.split("\n")
+        html_parts: list[str] = []
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Fenced code block
+            if line.strip().startswith("```"):
+                block, i = self._parse_code_block(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Table
+            if i + 1 < len(lines) and re.match(r"^\|.*\|$", line.strip()) and re.match(
+                r"^\|[\s\-:|]+\|$", lines[i + 1].strip()
+            ):
+                table, i = self._parse_table(lines, i)
+                html_parts.append(table)
+                continue
+
+            # Heading
+            if m := re.match(r"^(#{1,6})\s+(.+)$", line):
+                level = len(m.group(1))
+                text = self._inline(m.group(2))
+                anchor = self._make_anchor(text)
+                html_parts.append(
+                    f'<h{level} id="{anchor}">{text}</h{level}>'
+                )
+                i += 1
+                continue
+
+            # Horizontal rule
+            if re.match(r"^(\*{3,}|-{3,}|_{3,})\s*$", line.strip()):
+                html_parts.append("<hr>")
+                i += 1
+                continue
+
+            # Blockquote
+            if line.strip().startswith(">"):
+                block, i = self._parse_blockquote(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Unordered list
+            if re.match(r"^[\s]*[-*+]\s+", line):
+                block, i = self._parse_unordered_list(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Ordered list
+            if re.match(r"^[\s]*\d+\.\s+", line):
+                block, i = self._parse_ordered_list(lines, i)
+                html_parts.append(block)
+                continue
+
+            # Blank line
+            if not line.strip():
+                i += 1
+                continue
+
+            # Paragraph
+            para_lines: list[str] = []
+            while i < len(lines) and lines[i].strip() and not self._is_block_start(lines, i):
+                para_lines.append(lines[i])
+                i += 1
+            html_parts.append(f"<p>{self._inline(' '.join(para_lines))}</p>")
+
+        return "\n".join(html_parts)
+
+    def extract_toc(self, rendered_html: str) -> list[TocEntry]:
+        """Extract table-of-contents entries from rendered HTML."""
+        entries: list[TocEntry] = []
+        for m in re.finditer(r'<h(\d)\s+id="([^"]+)">(.*?)</h\1>', rendered_html):
+            entries.append(
+                TocEntry(
+                    level=int(m.group(1)),
+                    text=self._strip_tags(m.group(3)),
+                    anchor=m.group(2),
+                )
+            )
+        return entries
+
+    def extract_text(self, rendered_html: str) -> str:
+        """Strip all HTML tags and return plain text for indexing."""
+        text = re.sub(r"<[^>]+>", " ", rendered_html)
+        text = html.unescape(text)
+        return re.sub(r"\s+", " ", text).strip()
+
+    # ------------------------------------------------------------------
+    # Block parsers
+    # ------------------------------------------------------------------
+
+    def _parse_code_block(self, lines: list[str], start: int) -> tuple[str, int]:
+        opening = lines[start].strip()
+        lang = opening.lstrip("`").strip()
+        i = start + 1
+        code_lines: list[str] = []
+        while i < len(lines):
+            if lines[i].strip() == "```":
+                i += 1
+                break
+            code_lines.append(html.escape(lines[i]))
+            i += 1
+        lang_attr = f' class="language-{lang}"' if lang else ""
+        code = "\n".join(code_lines)
+        return f"<pre><code{lang_attr}>{code}</code></pre>", i
+
+    def _parse_table(self, lines: list[str], start: int) -> tuple[str, int]:
+        header_cells = [c.strip() for c in lines[start].strip().strip("|").split("|")]
+        i = start + 2  # skip separator
+        rows: list[list[str]] = []
+        while i < len(lines) and re.match(r"^\|.*\|$", lines[i].strip()):
+            cells = [c.strip() for c in lines[i].strip().strip("|").split("|")]
+            rows.append(cells)
+            i += 1
+        parts = ["<table>", "<thead><tr>"]
+        for cell in header_cells:
+            parts.append(f"<th>{self._inline(cell)}</th>")
+        parts.append("</tr></thead>")
+        if rows:
+            parts.append("<tbody>")
+            for row in rows:
+                parts.append("<tr>")
+                for cell in row:
+                    parts.append(f"<td>{self._inline(cell)}</td>")
+                parts.append("</tr>")
+            parts.append("</tbody>")
+        parts.append("</table>")
+        return "".join(parts), i
+
+    def _parse_blockquote(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        content_lines: list[str] = []
+        while i < len(lines) and lines[i].strip().startswith(">"):
+            content_lines.append(re.sub(r"^>\s?", "", lines[i]))
+            i += 1
+        inner = self._inline(" ".join(content_lines))
+        return f"<blockquote><p>{inner}</p></blockquote>", i
+
+    def _parse_unordered_list(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        items: list[str] = []
+        while i < len(lines) and re.match(r"^[\s]*[-*+]\s+", lines[i]):
+            text = re.sub(r"^[\s]*[-*+]\s+", "", lines[i])
+            items.append(f"<li>{self._inline(text)}</li>")
+            i += 1
+        return "<ul>" + "".join(items) + "</ul>", i
+
+    def _parse_ordered_list(self, lines: list[str], start: int) -> tuple[str, int]:
+        i = start
+        items: list[str] = []
+        while i < len(lines) and re.match(r"^[\s]*\d+\.\s+", lines[i]):
+            text = re.sub(r"^[\s]*\d+\.\s+", "", lines[i])
+            items.append(f"<li>{self._inline(text)}</li>")
+            i += 1
+        return "<ol>" + "".join(items) + "</ol>", i
+
+    # ------------------------------------------------------------------
+    # Inline formatting
+    # ------------------------------------------------------------------
+
+    def _inline(self, text: str) -> str:
+        """Apply inline Markdown transformations."""
+        # Inline code (must come before bold/italic to avoid conflicts)
+        text = re.sub(r"`([^`]+)`", r"<code>\1</code>", text)
+        # Images
+        text = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r'<img src="\2" alt="\1">', text)
+        # Links
+        text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'<a href="\2">\1</a>', text)
+        # Bold + italic
+        text = re.sub(r"\*\*\*(.+?)\*\*\*", r"<strong><em>\1</em></strong>", text)
+        # Bold
+        text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+        # Italic
+        text = re.sub(r"\*(.+?)\*", r"<em>\1</em>", text)
+        return text
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _is_block_start(self, lines: list[str], i: int) -> bool:
+        line = lines[i]
+        if re.match(r"^#{1,6}\s+", line):
+            return True
+        if line.strip().startswith("```"):
+            return True
+        if re.match(r"^[\s]*[-*+]\s+", line):
+            return True
+        if re.match(r"^[\s]*\d+\.\s+", line):
+            return True
+        if line.strip().startswith(">"):
+            return True
+        if re.match(r"^(\*{3,}|-{3,}|_{3,})\s*$", line.strip()):
+            return True
+        return False
+
+    def _make_anchor(self, text: str) -> str:
+        plain = self._strip_tags(text).lower()
+        slug = re.sub(r"[^\w\s-]", "", plain)
+        slug = re.sub(r"[\s]+", "-", slug).strip("-")
+        base = f"{self.heading_prefix}{slug}"
+        count = self._anchor_counts.get(base, 0)
+        self._anchor_counts[base] = count + 1
+        return base if count == 0 else f"{base}-{count}"
+
+    @staticmethod
+    def _strip_tags(text: str) -> str:
+        return re.sub(r"<[^>]+>", "", text)