Pudu programming language
Menu
Package

@chrismichaelps / pudu-lang-docgen

Documentation publishing for Pudu: articles, API references, navigation, search, and static websites

0.1.0Apache-2.01

InstallClose

introduction.md

Markdown57 lines3.8 KB

GitHub ↗

Introduction

uid: guides.introduction description: What pudu-lang-docgen is, what it produces, and how a build works.

pudu-lang-docgen is the documentation publishing package for Pudu. It reads a project folder described by a docgen.json file and writes a complete static website: articles written in Markdown, reference pages generated from the public declarations of Pudu modules, reference pages for HTTP services described with OpenAPI, navigation, a search index, a sitemap, and a cross-reference map that other sites can link against.

The package is a Pudu library. You can drive it from the command line through a small program that calls <xref:PuduLangDocgen.Command.run>, or call the build from your own code through <xref:PuduLangDocgen.Docset.build> and <xref:PuduLangDocgen.Build.plan>.

What a build produces

OutputSourceDescription
Article pages.md filesRendered HTML with an outline, permalinks, and a table of contents.
Pudu API reference.pudu filesOne page per module and per type, with signatures, documentation, and source links.
HTTP API referenceOpenAPI 3 or Swagger 2 in YAML or JSONOperations grouped by tag, parameters, bodies, responses, and schemas.
Catalog pages### YamlMime:Dashboard YAML filesCard galleries such as the [extension catalogs](../extensions/index.md).
Landing pages### YamlMime:Landing YAML filesA full-width banner, highlighted entry points, and topic lists, such as this site's home page.
Navigationtoc.yml, toc.json, or toc.mdTop bar, sidebar, breadcrumbs, and previous and next links.
index.jsonEvery indexable pageThe search index read by the site's search box.
sitemap.xmlEvery indexable pageA crawler map, written when sitemap is configured.
xrefmap.ymlEvery page and declaration with a uidA cross-reference map other sites can consume.
404.htmlGenerated unless you provide oneA not-found page for static hosts.
manifest.jsonThe whole buildEvery output file with the generator version.

How a build works

A build validates the whole site before it writes anything. If any error is found, nothing is published and every problem is reported with its file, line, and a stable diagnostic code.

flowchart LR
  A[docgen.json] --> B[Load project files]
  B --> C[Parse Markdown, Pudu sources, OpenAPI, and tables of contents]
  C --> D[Resolve links, cross references, and navigation]
  D --> E[Render pages through the template]
  E --> F{Any errors?}
  F -- no --> G[Publish changed files to _site]
  F -- yes --> H[Report diagnostics and write nothing]

Publishing is incremental: files whose content did not change are left untouched, and files that a previous build wrote but the current build no longer produces are removed. Build state is kept in the .docgen folder beside the configuration.

Design principles

  • Complete validation first. Broken links, missing images, unresolved cross references, and unknown table of contents targets are found before output is written.
  • Confined file access. Every path is checked to stay inside the project, symbolic links are not followed, and raw HTML in articles is reduced to a safe set of elements and attributes.
  • Static output. The result is plain HTML, CSS, and JavaScript that any static host can serve. Search runs in the browser.
  • Stable identities. Pages and declarations are addressed by uid, so links survive file moves and other sites can link to yours through the published cross-reference map.

Next steps