Module continuous_delivery_scripts.utils.documentation_discovery

Publish discovery files from a project's documentation and configuration.

Functions

def documentation_site_url() ‑> str | None

Expand source code

def documentation_site_url() -> str | None:
    """Use the configured URL, or a verified public GitHub Pages site."""
    value = configuration.get_value_or_default(ConfigurationVariable.DOCUMENTATION_SITE_URL, None)
    if not value:
        root = configuration.get_value_or_default(ConfigurationVariable.PROJECT_ROOT, None)
        if not root:
            return None
        remote = get_project_remote_url(Path(root))
        return github_pages_url(remote) if remote else None
    parts = urlsplit(str(value))
    if parts.scheme not in {"http", "https"} or not parts.hostname or parts.query or parts.fragment or parts.username:
        raise ValueError("DOCUMENTATION_SITE_URL must be a public HTTP(S) base URL without query or fragment")
    if parts.hostname in {"localhost", "127.0.0.1", "::1"}:
        raise ValueError("DOCUMENTATION_SITE_URL must point to a public site")
    return urlunsplit((parts.scheme, parts.netloc, parts.path.rstrip("/") + "/", "", ""))

Use the configured URL, or a verified public GitHub Pages site.

def publish_discovery_files(output: pathlib.Path,
root: pathlib.Path,
sources: pathlib.Path | None,
folder: pathlib.Path | None,
name: str,
module_to_document: str | None = None) ‑> None

Expand source code

def publish_discovery_files(
    output: Path,
    root: Path,
    sources: Path | None,
    folder: Path | None,
    name: str,
    module_to_document: str | None = None,
) -> None:
    """Copy authored files by source precedence or generate applicable resources."""
    site_url = documentation_site_url()
    guides = _published_guides(output, sources, folder)
    if site_url:
        _annotate_existing_pages(output, site_url, guides, folder)
    has_pages = any(output.rglob("*.html"))
    authored_directories = _authored_directories(root, sources, module_to_document)
    for filename in ("robots.txt", "sitemap.xml", "llms.txt", "llms-full.txt"):
        destination = output / filename
        authored = next(
            (directory / filename for directory in authored_directories if (directory / filename).is_file()), None
        )
        if authored:
            if authored.resolve() != destination.resolve():
                shutil.copyfile(authored, destination)
        elif site_url and has_pages and filename == "robots.txt":
            destination.write_text(
                documentation_templates()
                .get_template("robots.txt.jinja2")
                .render(sitemap_url=f"{site_url}sitemap.xml"),
                encoding="utf8",
            )
        elif site_url and has_pages and filename == "sitemap.xml":
            destination.write_text(_render_sitemap(output, site_url), encoding="utf8")
        elif site_url and (output / "index.html").is_file() and filename == "llms.txt":
            destination.write_text(_render_llms_index(output, site_url, name, guides, folder), encoding="utf8")
        elif site_url and filename == "llms-full.txt" and guides and folder:
            destination.write_text(_render_llms_full(output, site_url, name, guides, folder), encoding="utf8")

Copy authored files by source precedence or generate applicable resources.

def structured_data_script(title: str, description: str, url: str, schema_type: str) ‑> str

Expand source code

def structured_data_script(title: str, description: str, url: str, schema_type: str) -> str:
    """Represent only known page metadata as safe JSON-LD."""
    data = {
        "@context": "https://schema.org",
        "@type": schema_type,
        "name": title,
        "description": description,
        "url": url,
    }
    encoded = json.dumps(data, ensure_ascii=True).replace("<", "\\u003c")
    return f'<script type="application/ld+json">{encoded}</script>'

Represent only known page metadata as safe JSON-LD.