| """Content definitions for the AskMyDocs enterprise documentation corpus.
|
|
|
| Documents are defined as markdown strings generated by builder functions
|
| that accept a :class:`~scripts.corpus_shims.CorpusContext`, which keeps
|
| cross-references (document ids, usernames, feature flags) consistent.
|
|
|
| Sections / topics covered:
|
|
|
| docs 001-004 Authentication & security (auth, tokens, mfa, security)
|
| docs 005-009 OAuth / SSO / federation
|
| docs 010-014 API usage / references / errors
|
| docs 015-018 Configuration / feature flags
|
| docs 019-021 Deployment / environments
|
| docs 022-024 Monitoring / observability
|
| docs 025-027 User management / roles
|
| docs 028-031 Database behavior / troubleshooting / rate limits / webhooks
|
| """
|
|
|
| from __future__ import annotations
|
|
|
| from collections.abc import Callable
|
|
|
| from corpus_shims import front_matter, h2
|
|
|
|
|
|
|
|
|
|
|
|
|
| FACTS = {
|
| "api_key_prefix": "amsk_",
|
| "api_key_lifetime": "90 days",
|
| "oauth_provider": "OAuth 2.0",
|
| "token_expiry": "60 minutes",
|
| "refresh_token_expiry": "30 days",
|
| "rate_limit_default": "100 requests per minute",
|
| "rate_limit_burst": "300 requests per minute",
|
| "webhook_delivery": "HMAC-SHA256 signature",
|
| "webhook_retry": "5 retries, exponential backoff, max 10 minutes",
|
| "database_engine": "PostgreSQL 16",
|
| "db_connection_max": "100",
|
| "backup_retention": "30 days",
|
| "apitoken_claim": "permissions claim",
|
| "rbac_default_role": "viewer",
|
| "sso_saml": "SAML 2.0",
|
| "sso_oidc": "OpenID Connect",
|
| "sla_uptime": "99.95%",
|
| "pii_encryption": "AES-256 at rest",
|
| }
|
|
|
|
|
|
|
|
|
|
|
|
|
| def doc(
|
| doc_id: str,
|
| title: str,
|
| version: str,
|
| module: str,
|
| *sections: Callable[[], str],
|
| ) -> str:
|
| """Compose a document from front matter + sections."""
|
| parts: list[str] = [front_matter(doc_id=doc_id, title=title, version=version, module=module)]
|
| parts.extend(s() for s in sections)
|
| return "\n".join(parts)
|
|
|
|
|
| def numbered_section(num: int, title: str, body: str) -> str:
|
| return h2(f"{num}. {title}") + body
|
|
|
|
|
| def create_auth_context() -> dict[str, str]:
|
| """Context fields shared across auth-related documents."""
|
| return {
|
| "api_key_prefix": FACTS["api_key_prefix"],
|
| "token_expiry": FACTS["token_expiry"],
|
| "refresh_token_expiry": FACTS["refresh_token_expiry"],
|
| } |
