manager/client-docs/index.php

<?php

declare(strict_types=1);

/**
 * Public client handbook (Markdown -> HTML via the vendored marked.js).
 *
 * Same shape as the two viewers inside the repository: an index plus one page
 * per document, reached as index.php?doc=KEY. In addition every source file of
 * the client package has its own page, index.php?code=PATH.
 *
 * Self-contained: no build step and no external requests. The pages are read
 * from client-package/ on each request, so they always match the repository.
 *
 * Agents do not read this rendering - the head of every page points at the
 * Markdown twin under llms.php; see the hint below.
 */

require_once __DIR__ . "/inc/handbook.php";

$pages = handbookPages();
$docs = handbookPagesOfKind("doc");
$code = handbookPagesOfKind("code");

$requestedDoc = isset($_GET["doc"]) ? (string) $_GET["doc"] : "";
$requestedCode = isset($_GET["code"]) ? (string) $_GET["code"] : "";

$page = null;
$markdown = null;
$pageTitle = "Overview";
$notFound = false;

if ($requestedDoc !== "" || $requestedCode !== "") {
    $page = $requestedDoc !== ""
        ? handbookPage("doc", $requestedDoc)
        : handbookPage("code", $requestedCode);

    if ($page === null) {
        http_response_code(404);
        $pageTitle = "Not Found";
        $notFound = true;
    } else {
        $markdown = handbookPageMarkdown($page);
        $pageTitle = $page["title"];
    }
}

// Works both when client-docs/ is a subdirectory and when it is served as the
// web root (php -S localhost:8080 -t client-docs), where dirname() yields "/".
$baseHref = rtrim(str_replace("\\", "/", dirname($_SERVER["SCRIPT_NAME"] ?? "")), "/") . "/";
if ($baseHref === "") {
    $baseHref = "/";
}

$indexUrl = handbookSelfUrl() . "/llms.php";
$rawUrl = $page !== null ? handbookRawUrl($page) : $indexUrl;
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?php echo handbookEscape($pageTitle); ?> – Manage Client</title>
    <link rel="stylesheet" href="<?php echo handbookEscape($baseHref); ?>assets/docs.css">
    <link rel="alternate" type="text/markdown" href="<?php echo handbookEscape($rawUrl); ?>"
          title="This page as Markdown">
</head>
<body>
<!--
    Note for LLMs and other programs:

    This page renders its content only in the browser. The text is therefore
    not in this HTML. The same page as plain Markdown, unstyled:

        <?php echo $rawUrl . "\n"; ?>

    Index of every page, with a short description and size, so you can load
    only what you need:

        <?php echo $indexUrl . "\n"; ?>
-->
<p class="llm-only">
    For LLMs: this page as Markdown at <?php echo handbookEscape($rawUrl); ?> –
    index of every page at <?php echo handbookEscape($indexUrl); ?>
</p>
<header class="docs-header">
    <div class="docs-header-inner">
        <a class="docs-brand" href="<?php echo handbookEscape($baseHref); ?>index.php">Manage Client</a>
        <nav class="docs-header-links">
            <a href="<?php echo handbookEscape($baseHref); ?>api.php">API Reference</a>
            <a href="<?php echo handbookEscape($baseHref); ?>llms.php">For LLMs</a>
        </nav>
    </div>
</header>
<div class="docs-layout">
    <nav class="docs-nav" aria-label="Documentation">
        <p class="docs-nav-title">Documentation</p>
        <ul>
            <?php foreach ($docs as $entry): ?>
                <li>
                    <a href="<?php echo handbookEscape($baseHref); ?>index.php?<?php echo handbookEscape(handbookPageQuery($entry)); ?>"
                       <?php echo handbookIsSamePage($page, $entry) ? 'aria-current="page"' : ""; ?>>
                        <?php echo handbookEscape($entry["nav"]); ?>
                    </a>
                </li>
            <?php endforeach; ?>
        </ul>

        <p class="docs-nav-title">Interface</p>
        <ul>
            <li><a href="<?php echo handbookEscape($baseHref); ?>api.php">Swagger UI</a></li>
            <li><a href="<?php echo handbookEscape($baseHref); ?>openapi.php">OpenAPI document</a></li>
        </ul>

        <p class="docs-nav-title">Source Code</p>
        <ul class="docs-nav-code">
            <?php foreach ($code as $entry): ?>
                <li>
                    <a href="<?php echo handbookEscape($baseHref); ?>index.php?<?php echo handbookEscape(handbookPageQuery($entry)); ?>"
                       <?php echo handbookIsSamePage($page, $entry) ? 'aria-current="page"' : ""; ?>>
                        <?php echo handbookEscape($entry["nav"]); ?>
                    </a>
                </li>
            <?php endforeach; ?>
        </ul>
    </nav>
    <main class="docs-main">
        <?php if ($page === null && !$notFound): ?>
            <h1>Manage Client</h1>
            <p>Update and backup functionality for standalone PHP projects: the
                complete documentation of the client package, its entire source code,
                and the interface to the Manage server.</p>
            <p>Every chapter and every source file has its own page; the list is on
                the left and again below, each with one sentence about what's on it.</p>
            <p>For programs, the same pages exist as plain Markdown:
                <a href="<?php echo handbookEscape($baseHref); ?>llms.php">llms.php</a> is the
                index for that, and additionally names which pages are needed for which
                task.</p>

            <h2>Documentation</h2>
            <p>In the recommended reading order.</p>
            <dl class="docs-index-list">
                <?php foreach ($docs as $entry): ?>
                    <dt>
                        <a href="<?php echo handbookEscape($baseHref); ?>index.php?<?php echo handbookEscape(handbookPageQuery($entry)); ?>">
                            <?php echo handbookEscape($entry["nav"]); ?>
                        </a>
                    </dt>
                    <dd><?php echo handbookSummaryHtml($entry["summary"]); ?></dd>
                <?php endforeach; ?>
            </dl>

            <h2>Interface</h2>
            <dl class="docs-index-list">
                <dt><a href="<?php echo handbookEscape($baseHref); ?>api.php">API reference</a></dt>
                <dd>Protocol v1 in Swagger UI, to look up and try out</dd>
                <dt><a href="<?php echo handbookEscape($baseHref); ?>openapi.php">OpenAPI document</a></dt>
                <dd>The same description as OpenAPI 3.1, for code generators</dd>
            </dl>

            <h2>Source Code</h2>
            <p>The complete client package. Integrating it needs the folder
                <code>manage-client/</code>; <code>examples/</code>,
                <code>docs/</code> and <code>scripts/</code> are not part of that.</p>
            <dl class="docs-index-list docs-index-code">
                <?php foreach ($code as $entry): ?>
                    <dt>
                        <a href="<?php echo handbookEscape($baseHref); ?>index.php?<?php echo handbookEscape(handbookPageQuery($entry)); ?>">
                            <?php echo handbookEscape($entry["nav"]); ?>
                        </a>
                        <span class="docs-size"><?php echo handbookEscape(handbookFormatBytes($entry["bytes"])); ?></span>
                    </dt>
                    <dd><?php echo handbookSummaryHtml($entry["summary"]); ?></dd>
                <?php endforeach; ?>
            </dl>
        <?php elseif ($notFound): ?>
            <h1>Not Found</h1>
            <p>The requested page doesn't exist.</p>
            <p><a href="<?php echo handbookEscape($baseHref); ?>index.php">Back to the overview</a></p>
        <?php else: ?>
            <p class="docs-source-note">
                Source: <code><?php echo handbookEscape($page["source"]); ?></code>
                · <?php echo handbookEscape(handbookFormatBytes($page["bytes"])); ?>
                · <a href="<?php echo handbookEscape($rawUrl); ?>">as Markdown</a>
            </p>
            <article id="doc-content" class="markdown-body"></article>
            <script type="application/json" id="doc-source"><?php
                echo json_encode(
                    $markdown,
                    JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE,
                );
            ?></script>
        <?php endif; ?>
    </main>
</div>
<?php if ($markdown !== null): ?>
    <script src="<?php echo handbookEscape($baseHref); ?>assets/marked.min.js"></script>
    <script>
        (function () {
            var source = document.getElementById('doc-source');
            var target = document.getElementById('doc-content');
            if (!source || !target || typeof marked === 'undefined') {
                return;
            }
            target.innerHTML = marked.parse(JSON.parse(source.textContent || '""'), {
                gfm: true,
                breaks: false
            });
        })();
    </script>
<?php endif; ?>
</body>
</html>