internal/docsite

github.com/ensera-ai/taisce/internal/docsite · 7 files · 2184 lines · 20 tests · source

Package docsite assembles the source of the documentation site: the written documents where they stand, and a reference generated from the repository and from a freshly migrated database.

Why the reference is generated

A hand-written description of every declaration is a second copy of the code, and it is wrong the first time somebody edits a function without knowing the page exists. Nothing fails when that happens, so nobody notices. Generating the reference from the source means it is as current as the commit it was built from. It also means it is only as good as the doc comments it renders, which is the right pressure: the comment next to the code is the one a reviewer sees.

The schema reference is introspected from a database the migrations have just built rather than parsed from their text. The SQL says what was asked for; the catalog says what PostgreSQL made of it after sixty-odd migrations altered one another, and that is what a reader needs.

What this package is allowed to decide

Page layout, link resolution, the navigation, and what the build refuses. It does not decide what a written document says: those are in docs/ and are rendered as they are. It does not render anything either; the renderer in site/ does, and this package hands it markdown and a sidebar definition. It never writes into the repository's docs/. It writes only the directory and the file it is given, and the only database it creates is a scratch database, which it drops.

What the build refuses

• A package with no doc comment, because that comment is where a package says what it may decide and what it must not.
• A link that names nothing, because a reader who follows one stops trusting the rest.
• A document in docs/ that the navigation neither lists nor keeps in the repository, because a page nobody can reach looks published and is not, and a record written for contributors should not reach the site by being forgotten.
• A document both listed and kept, or a kept name that is no document, because either means the navigation no longer says what the site shows.

The renderer then refuses a link or an anchor that names nothing on the rendered site. A build that published with any of these would be a site that looks complete and is not.

Where it sits

Imports: internal/migrate

Imported by: none in this repository

Files

File	Lines	Declarations	What it is for
code.go	646	31	module is the import path prefix that marks a package as this repository's own.
docsite.go	390	17	Carries the package documentation.
links.go	179	7	resolveLinks rewrites every page's links in place and reports every broken one at once, so a run names the whole list rather than the first.
migrations.go	278	16	sentence turns a file name back into the sentence it was named with.
schema.go	464	19	withScratchDatabase creates an empty database on the substrate, gives it the extensions the substrate image gives its own database at first start, bootstraps it, hands a pool on it to fn, and drops it afterwards whatever fn returned.
sidebars.go	101	7
tooling.go	126	4	makeTargets pairs each target with the comment block directly above it.

20 tests hold this package's behaviour; the list is named for what each one proves.