On this page
Resolving the content directives that need no language extractor: the five callouts, the glossary list, and the filesystem and project-metadata tables.
#internal/content
#internal/content
Package content resolves the content directives: the ones that need no language extractor.
They cover the five callouts, the glossary list, and the filesystem and project-metadata directives (list-tree, table-dep, list-modules, table-commands, table-directives, table-config-schema, table-endpoint, var and cv).
#One dispatch, no registry
The Python this replaces had two content modules and a directive registry between them: table-commands reads a strictcli schema, the schema reader lived in the application package, and the core package it had to be dispatched from was forbidden to import that package. The registry existed to carry one function across that boundary. One Go module has no such boundary, so table-commands is an ordinary branch of ResolveContent like every other directive, and the registry is gone -- along with the questions it raised (when is a resolver registered, what happens to a build that never imported the module that registers it).
#VersionOverrideKey
const VersionOverrideKey = "_version_override"VersionOverrideKey is a runtime-only config key carrying an explicit project version.
It is never read from or written to selfdoc.json: the callers that own it (gen and check, under their --version-override flag) inject it into the already-loaded config, which is the object that reaches every directive resolver. That single injection point covers root-file generation at gen time and site pages at build time.
#ContentDirectives
var ContentDirectives = map[string]struct{}{ContentDirectives is every directive name this package resolves.
#ErrNoSourceEntries
var ErrNoSourceEntries = errors.New("selfdoc.json declares no 'source' entries")ErrNoSourceEntries is returned by the directives that read source code when the project declares none.
A placeholder note would hide the fact that the page lost the listing it asked for, and a codeless project usually has no source directory on disk either -- so the missing-source check runs before the directory check, or the build would render "directory not found" and exit 0.
#ResolveGlossary
func ResolveGlossary(body []string) stringResolveGlossary parses glossary body lines into HTML with dl/dt/dd elements.
Each non-empty line is expected as "Term: Definition text". The "**" markers are stripped and the term and definition are split on the first ": " separator. The result is wrapped in
#ResolveContent
func ResolveContent(ResolveContent resolves a content directive.
The second result is false when name is not a content directive at all, which is how the resolver learns to try the language extractors instead. An error is the hard-error family: a directive that reads source code in a project that declares none, a malformed CV, or a schema this project cannot name -- each a condition where rendering a placeholder note would hide the fact that the page lost the content it asked for.
config is the loaded selfdoc.json and may be nil, which several directives report in band because a build without a config still renders its pages.
#ResolveCV
func ResolveCV(attrs map[string]string, config map[string]any, baseDir string) (string, error)ResolveCV renders the CV declared at the path attribute as the page's body.
Every failure is a hard error naming what is wrong: a missing path, a document that is not there, a malformed declaration, or a build with no author to state the Person from. A CV page that rendered a placeholder would publish a person's record with holes in it.
#ResolveListModules
func ResolveListModules(ResolveListModules lists source modules grouped by the language's natural unit: one bullet per package for Go, per file grouped by directory for TypeScript and JavaScript, and per file for Python and everything else.
With files=true the per-file listing is used whatever the language, which is also the only listing an unsupported language can have.
#ResolveListTree
func ResolveListTree(attrs map[string]string, baseDir string) stringResolveListTree walks a directory and produces a text tree inside a fenced code block.
#ResolveTableDirectives
func ResolveTableDirectives() (string, error)ResolveTableDirectives produces a Markdown table of every core built-in directive, in name order.
#ResolveTableConfigSchema
func ResolveTableConfigSchema() (string, error)ResolveTableConfigSchema produces a Markdown table of the selfdoc.json configuration fields, in schema order.
A field marked internal is left out: it is a runtime key rather than something an author writes, so documenting it would invite a declaration that is not one.
#ResolveTableCommands
func ResolveTableCommands(attrs map[string]string, config map[string]any, baseDir string) (string, error)ResolveTableCommands produces a Markdown table of the CLI commands a strictcli schema declares.
The .strictcli/schema.json is discovered by walking the project root. When exactly one schema is found it is used; zero and several are both hard errors, and schema-dir="
#ResolveTableDep
func ResolveTableDep(attrs map[string]string, baseDir string) stringResolveTableDep parses a pyproject.toml and produces a Markdown dependency table: the project's own dependencies, then one labelled block per optional-dependency group, in the order the document declares them.
#ResolveTableEndpoint
func ResolveTableEndpoint(attrs map[string]string, baseDir string) (string, error)ResolveTableEndpoint renders REST API endpoint documentation from an OpenAPI 3.x JSON specification.
#ResolveVar
func ResolveVar(attrs map[string]string, config map[string]any, baseDir string) (string, error)ResolveVar interpolates a project metadata value.