NaviServer Programmable Web Server

admin-doc(n)

NaviServer Manual – 5.2.0a


[ Main Table Of Contents | Table Of Contents | Keyword Index ]

Name

admin-doc - Building Core and Module Documentation

Table Of Contents

Description

NaviServer and its external modules maintain documentation in their own repositories. Shared build tools generate parameter references from Tcl dictionaries and render doctools manuals as HTML and nroff. Modules can build standalone documentation or contribute to a combined NaviServer manual. Ordinary software builds use committed parameter fragments and do not require the documentation toolchain.

Source Layout and Ownership

Core parameter descriptions remain in "doc/tcl/config-parameters.tcl". Each external module owns its dictionary at the same relative location in its repository. A module dictionary extends ::ns_configdoc::data with its own modules entry; it does not replace the core dictionary.

 namespace eval ::ns_configdoc {}
 dict set ::ns_configdoc::data modules example {
     enabled {
         type boolean
         default false
         desc {Enable this example module.}
     }
 }

Module repositories use this layout:

"doc/tcl/config-parameters.tcl"

Authoritative parameter descriptions and metadata.

"doc/src/include/parameters.man"

Generated parameter reference. Commit this fragment alongside its source dictionary.

"doc/src/MODULE.man"

Complete module manual, including its local parameter fragment with [include include/parameters.man].

"doc/html/"

Generated standalone HTML documentation.

"doc/man/"

Generated standalone nroff documentation.

Module Versions and README Badges

Define NS_MODULE_VERSION once in the module Makefile, before including "Makefile.module". If a Tcl module supplies "version.tcl.in", the shared rules generate and install "version.tcl". This file defines only module-owned variables; the module's "init.tcl" sources it and registers metadata before initializing other module functionality:

 # version.tcl.in
 namespace eval ::example {}
 set ::example::version {@NS_MODULE_VERSION@}
 set ::example::tag {@NS_MODULE_TAG@}
 
 # init.tcl
 source [file join [file dirname [info script]] version.tcl]
 ns_module version $::example::version
 ns_module tag $::example::tag

The ordinary loader may subsequently source "version.tcl" again. Since it only assigns variables, this does not register metadata twice. Modules supporting older cores can wrap the two ns_module calls in a single catch.

If "version.svg.in" is present, the same version value generates ".version.svg". Reference that local SVG from a normal Markdown README with ![Version](.version.svg). Both templates substitute @NS_MODULE_VERSION@ and @NS_MODULE_TAG@. The tag defaults to git describe; outside Git, the existing generated Tcl metadata preserves the recorded tag. Unchanged generated contents retain their timestamps. Commit both templates and their generated outputs for source archives and README rendering without a build.

The input/output names can be overridden with TCL_VERSION, TCL_VERSION_FILE, VERSION_SVG and VERSION_SVG_FILE. The existing TCL_INIT/TCL_INIT_FILE entry-point templates remain supported. Binary and mixed modules keep metadata in their native callback; automatic "version.tcl.in" discovery is disabled when MOD is set. They can still use the SVG template without declaring metadata twice.

Toolchain and Module Build Targets

NaviServer installs shared tools under "share/naviserver/doc/tools". They require Tcl 8.6 or newer. Parameter regeneration also requires NSF/NX; rendering and validation require Tcllib doctools/dtplite.

When MODNAME is set and the repository-local dictionary is present, "Makefile.module" supplies these targets:

make regen-config-parameters-includes

Regenerate the committed parameter fragment from the module dictionary.

make check-config-parameters

Compare the fragment with generated text without changing files. Missing or stale fragments cause an error.

make check-doc

Check fragment freshness and validate the complete module manuals.

make build-doc

Build standalone HTML and nroff documentation. Uses the committed fragment; regeneration remains an explicit operation.

For development with source-checkout tools, use:

 make check-doc DOC_TOOLS=/path/to/naviserver/doc/tools
 make build-doc DOC_TOOLS=/path/to/naviserver/doc/tools

The variables MODULE_CONFIG_PARAMETERS, MODULE_PARAMETER_INCLUDE, MODULE_DOC_HTML and MODULE_DOC_MAN can override the default paths. make config-parameters-includes REGEN_CONFIG_PARAMETERS=1 also explicitly regenerates module parameter documentation.

Installed Parameter Help

Module installation copies its dictionary to "tcl/MODULE/doc/tcl/config-parameters.tcl" beneath the NaviServer installation prefix. nsstats loads available installed module dictionaries after the core dictionary for configuration help. Missing optional dictionaries do not prevent displaying the configuration page. Descriptions therefore follow the installed module rather than a snapshot maintained in the core repository.

Combined Documentation

A core-only documentation build remains independent of external repositories:

 make build-doc

Explicitly select locally available module repositories for a combined build:

 make build-doc EXTERNAL_MODULE_DOCS="/path/to/nsstats /path/to/nssmtpd"

Each repository directory name identifies its module. Assembly preserves the module's "doc/src" tree beneath that name in the temporary documentation tree, including relative includes. It also copies the generated parameter fragment into a namespaced include directory and adds it to the core configuration reference. The dtplite merge builds combined navigation and cross-references.

The build never fetches repositories or copies module sources back into the core source tree. Missing or stale selected fragments are errors; run the module's freshness check before publication.

The shared builder also supports independent staging:

 tclsh build-module-doc.tcl --source /path/to/nssmtpd --module nssmtpd --stage /tmp/doc-stage

A staging destination must be fresh for each selected module. Duplicate module names fail rather than overwriting another module's documentation.

See Also

admin-config, admin-config-params, admin-install

Keywords

configuration, doctools, documentation, dtplite, modules, parameters