proc primaryDocPath(report: DocBuildReport): string {. ...raises: [ValueError, OSError], tags: [ReadDirEffect, RootEffect], forbids: [].}
Discovers modules and orchestrates Nim API documentation generation.
Types
DocBuildOptions = object profile*: string ## Profile whose flags are applied to Nim doc. features*: FeatureSelection ## Enabled features applied to Nim doc. verbose*: bool ## Whether Nim doc commands are printed. outDir*: string ## Output directory override. entrypoints*: seq[string] ## Additional documentation entrypoint files. skipExamples*: bool ## Skip compiling runnable examples. includePrivate*: bool ## Include private symbols in generated API docs. noIndex*: bool ## Suppress Bau's documentation index generation.
- Runtime options for API documentation generation.
DocBuildReport = object ok*: bool ## True when every Nim doc invocation succeeded. outDir*: string ## Absolute output directory. indexPath*: string ## Expected generated index path. modules*: seq[DocModule] ## Modules selected for documentation. diagnostics*: seq[DocDiagnostic] ## Non-fatal documentation diagnostics. commands*: seq[DocCommandResult] ## Nim doc command results. generatedFiles*: seq[string] ## Generated files relative to `outDir`.
- Complete result of a documentation build.
DocCommandResult = object moduleName*: string ## Module documented by the command. file*: string ## Project-relative source path. outputPath*: string ## Expected generated HTML path. command*: seq[string] ## Full command argv. exitCode*: int ## Process exit code. output*: string ## Combined compiler output.
- Result of one Nim doc invocation.
DocDiagnostic = object kind*: string ## Stable diagnostic kind. file*: string ## Project-relative file path. message*: string ## Human-readable diagnostic message.
- Documentation-quality diagnostic.
DocModule = object file*: string ## Absolute source file path. relPath*: string ## Project-relative source file path. sourceRelPath*: string ## Source-root-relative path used for output naming. moduleName*: string ## Dotted module name shown in reports. outputPath*: string ## Expected generated HTML path. entrypoint*: bool ## True when selected as an explicit entrypoint.
- One Nim source file selected for documentation.
Consts
DocManifestName = ".bau-docs-manifest"
- Manifest listing files produced by bau doc.
Procs
proc buildApiDocs(cfg: BauConfig; projectDir: string; opts: DocBuildOptions = DocBuildOptions()): DocBuildReport {. ...raises: [ValueError, OSError, IOError, KeyError], tags: [ReadDirEffect, RootEffect, ReadIOEffect, WriteDirEffect, ReadEnvEffect, WriteIOEffect, ExecIOEffect, TimeEffect], forbids: [].}
-
Generate Nim API documentation and return a structured build report.
Previously generated files tracked by Bau's manifest are removed before invoking Nim doc.
proc discoverDocModules(cfg: BauConfig; projectDir: string; opts: DocBuildOptions = DocBuildOptions()): seq[ DocModule] {....raises: [ValueError, OSError], tags: [ReadDirEffect, RootEffect], forbids: [].}
-
Discover Nim modules that should be documented for a project.
Explicit entrypoints and include/exclude patterns are resolved before the final list is sorted by project-relative path.
proc docReportJson(report: DocBuildReport): JsonNode {. ...raises: [ValueError, OSError], tags: [ReadDirEffect, RootEffect], forbids: [].}
- Convert a documentation build report to JSON.
- Return the preferred HTML file to open for a documentation report.