complex_docs
A documentation-heavy project planning library used to exercise registry SSR and docs rendering.
ssr
documentation
planning
example
moon add ssrfixture/complex_docs@0.1.0
Download zip
README#Complex Docs: a registry and SSR verification fixture
ssrfixture/complex_docs is a deliberately documentation-heavy MoonBit module.
It models a small project-planning domain, but its primary purpose is to make
registry, documentation builder, object storage, server-side rendering, and
hydration problems easy to see. Tiny packages often produce plausible-looking
pages even when only the shell rendered. This package instead supplies multiple
packages, several public types, long API comments, tables, examples, and enough
narrative prose that an incomplete render is immediately obvious.
SSR_COMPLEX_PACKAGE_README_MARKER is a stable marker for automated and
manual checks. If a generated documentation page contains this sentence, the
README resource was fetched and rendered rather than replaced by a loading
skeleton or an empty fallback.
#What the module contains
The module is split into four public packages. The root package provides a
realistic fixture and convenience functions. model owns domain values and
validation errors. planner computes deterministic schedules and progress
summaries. report converts the combined data into Markdown suitable for build
logs, release notes, or static documentation.
This arrangement is intentionally more representative than a single hello
function. Documentation generation must discover several package directories,
connect cross-package type references, render public fields and enum variants,
and preserve links between functions whose signatures mention types defined in
other packages.
#Domain model
A project contains a name, a long-form summary, and an ordered array of tasks.
Each task carries an integer identifier, a title, a detailed description, a
priority, a lifecycle state, an estimate, dependencies, and tags. Dependencies
use task identifiers instead of nested task values. This keeps serialized data
compact and avoids recursive object graphs while remaining easy to inspect in
generated documentation.
Priority and state are separate concepts. Priority records intent and remains
useful after work finishes. State records current lifecycle progress. A critical
task can therefore be completed without losing the information that it was
critical, and historical reports can explain why it received attention.
The validator checks several structural invariants:
- Project names must not be empty.
- Task titles must contain text.
- Estimates must be positive.
- Task identifiers must be unique within a project.
- Every dependency must point to a task in the same project.
Validation reports the first problem in deterministic task order. This keeps
command-line output stable and makes snapshot tests reproducible. Applications
that need a full list can validate individual tasks or layer an aggregation API
on top of the provided error values.
#Planning behavior
The planner is intentionally transparent. It preserves input order and assigns
half-open point ranges to unfinished tasks. A task starting at point 3 and ending
at point 8 consumes five points, and the next task can start at 8 without an
overlap. Finished or cancelled tasks do not consume new schedule space.
Urgency begins with the task's priority weight. In-progress work receives a
small continuity bonus, blocked work receives a small penalty, and finished
work receives zero. This is not intended as a universal prioritization formula;
it is a compact, deterministic example whose result can be understood directly
from API documentation without hidden services or statistical models.
The summary reports total tasks, finished tasks, remaining estimate points, and
open critical tasks. Cancelled work counts as finished for remaining-work
purposes but remains distinguishable from completed work in the underlying
model. Open critical task count is operational: historical completed critical
tasks do not keep the alert permanently elevated.
#Quick example
test "build and render a plan" {
let project = @complex_docs.demo_project()
@model.validate(project)
let summary = @planner.summarize(project)
assert_eq(summary.total_tasks, 3)
let markdown = @report.to_markdown(project)
assert_true(markdown.contains("Schedule"))
}The built-in fixture describes the exact workflow used to create this module:
map the rendering pipeline, publish a substantial package through the real local
registry, and verify that native SSR contains both README and API markers. Its
descriptions are long on purpose so line wrapping, paragraph spacing, search
indexing, and server output size are all exercised.
#SSR verification checklist
When using this package to inspect a registry deployment, verify each layer
independently before treating a rendered page as correct.
#Manifest request
The manifest resolves an unversioned module path to a concrete version and
reports whether documentation generation succeeded. If this request goes to a
production proxy while the package only exists locally, the page may still show
the path parsed from the URL but it will not contain package metadata.
#Module index
The module index describes packages, types, traits, errors, functions, and source
locations. Its presence should produce a populated sidebar and working search
entries. A header alone does not prove that the module index arrived.
#Package data
Package data contains the detailed API documentation rendered in the main
content area. Look for Priority, TaskState, Task, Project,
ValidationError, ScheduleEntry, and PlanSummary. Missing API sections often
mean the SSR runtime returned before second-wave requests completed.
#README resource
The README resource contains this document. Search the final HTML for
SSR_COMPLEX_PACKAGE_README_MARKER. If the marker appears only in an API payload
or JavaScript bundle but not in the server-generated body, the page has not
completed its documentation render.
#API marker
The root function demo_report documents
SSR_COMPLEX_PACKAGE_API_MARKER. Checking both markers distinguishes a loaded
README from loaded API documentation and makes stale or partially uploaded
objects easier to diagnose.
#Why the asset origin matters
Native rendering resolves relative HTTP requests against the URL passed to the
application renderer. For a page URL on a local frontend origin, /api and
/assets therefore return to that same origin. A development gateway must proxy
both paths consistently: /api to the local read service and /assets to the
documentation bucket in local object storage.
Changing only the browser's compile-time API endpoint does not necessarily
change native SSR. Browser JavaScript can call an absolute backend URL while the
native renderer still follows relative URLs. This fixture makes that mismatch
visible because its local-only module cannot be found through the production
registry or production asset CDN.
#Hydration expectations
The server and browser should begin from compatible route and data states. A
server render that contains a loading skeleton may look acceptable after client
JavaScript fetches the missing data, but it loses the discoverability, latency,
and no-JavaScript benefits expected from SSR. Conversely, fully rendered server
HTML without compatible hydration state may be discarded and rebuilt on the
client.
Use this package to compare the initial HTML response, the DOM immediately
before hydration, and the DOM after the application becomes idle. The markers,
long descriptions, schedule table, and repeated API sections provide several
independent signals instead of relying on a single title.
#Operational notes
This module has no external dependencies beyond MoonBit's standard environment.
That keeps documentation builds deterministic and isolates registry behavior
from third-party availability. It also means failures are usually attributable
to publishing, indexing, build workers, object storage, routing, or rendering
rather than dependency resolution.
The package is intentionally verbose but computationally small. It is safe to
publish repeatedly under new semantic versions when testing cache invalidation.
Do not overwrite an existing version: registries normally treat published
versions as immutable, and the local environment follows that rule to expose
the same operational behavior as production.
#License
The fixture is licensed under Apache-2.0. Its text, examples, and public API are
designed for local integration tests and may be copied into automated registry
verification workflows.
#demo_project
Builds a realistic project used throughout this module's documentation.
The fixture contains dependencies, multiple priorities, a completed task,
long descriptions, and enough scheduling metadata to exercise every public
reporting function. It is useful in doctests, demonstrations, SSR snapshots,
and manual registry checks.
#demo_report
fn demo_report() -> StringReturns a long Markdown report containing a unique SSR verification marker.
Search generated HTML for SSR_COMPLEX_PACKAGE_API_MARKER to confirm that
API documentation and function bodies were generated from this version of
the package rather than a stale registry object.
#validated_status
Validates the built-in fixture and returns its compact progress line.
Source Files
A documentation-heavy project planning library used to exercise registry SSR and docs rendering.
ssrdocumentationplanningexample
0.1.0
Apache-2.0