Assemble MonoDoc Documentation with mdassembler

mdassembler packages a directory of documentation into the tree and zip files that monodoc can display. This guide builds both, plus the small XML descriptor that tells MonoDoc where to show them, and keeps the build separate from installation so nothing touches your live MonoDoc setup until you say so.

Allow about twenty minutes for a first assembly. You need the monodoc-base package, a directory of documentation in a supported format, and write access to a working directory. Installing into MonoDoc's shared sources directory needs elevated privileges.

1. Check which assembler you have

The name mdassembler is obsolete in the installed manual, superseded by mdoc assemble. On this machine, the command comes from monodoc-base version 6.8.0.105+dfsg-3.6ubuntu2, and its version output identifies the implementation as mdoc 5.7.4.9. Check your own host rather than assuming another Mono installation behaves the same way:

$ command -v mdassembler
/usr/bin/mdassembler
$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-base
monodoc-base 6.8.0.105+dfsg-3.6ubuntu2
$ mdassembler --version
mdoc 5.7.4.9
$ mdassembler --help
usage: mdoc assemble [OPTIONS]+ DIRECTORIES

2. Identify the input format and output prefix

The old interface uses one format switch and one or more input paths. The man page lists --ecma, --ecmaspec, --error, --man, --simple and --xhtml. Use --ecma for normal Mono API XML produced by monodocer, --simple for a directory of text files, and --man for man pages.

Choose a prefix without a filename extension: the assembler appends .tree and .zip to it. Keep the prefix identical in the later .source file. For example, if the input is docs/en, build /tmp/my-library like this:

$ mkdir -p /tmp/my-library-build
$ mdassembler --ecma --out /tmp/my-library-build/my-library docs/en

The equivalent modern command on this installation is:

$ mdoc assemble --format=ecma --out /tmp/my-library-build/my-library docs/en

Do not mix formats casually. An ECMA source tree needs the ecma provider later, while man, simple and XHTML inputs need their corresponding provider names.

3. Verify the generated bundle before installation

Inspect the exact files rather than assuming a zero exit status is enough:

$ test -s /tmp/my-library-build/my-library.tree && echo 'tree: present'
tree: present
$ test -s /tmp/my-library-build/my-library.zip && echo 'zip: present'
zip: present
$ file /tmp/my-library-build/my-library.tree /tmp/my-library-build/my-library.zip
/tmp/my-library-build/my-library.tree: data
/tmp/my-library-build/my-library.zip: Zip archive data

Exact file descriptions vary by distribution. The useful checkpoint is that both files exist, are non-empty, and share a prefix. If either test fails, stop and read the assembler's diagnostic rather than copying a partial result into the system sources directory.

A zero exit status only proves the command completed. It does not prove every API page is complete or that the source will appear in the tree, so validate freshly generated or changed input documentation with the appropriate Mono documentation tools before assembling it.

4. Write the matching source descriptor

Create my-library.source beside the generated files. Its provider must match the input format, its basefile must be the prefix without .tree or .zip, and its path must name a valid MonoDoc tree location. This example places the library under the existing libraries node:

<?xml version="1.0"?>
<monodoc>
  <node label="My Library" name="my-library" parent="libraries" />
  <source provider="ecma" basefile="my-library" path="my-library" />
</monodoc>

basefile is not a path and must not include an extension. path connects the source to the tree node. Using a different parent or path means checking MonoDoc's installed monodoc.xml for valid node names first: a typo here can leave a perfectly good bundle invisible in the browser.

$ ls -l /tmp/my-library-build/my-library.source \
    /tmp/my-library-build/my-library.tree \
    /tmp/my-library-build/my-library.zip

5. Install the source with elevated privileges

Find the active MonoDoc sources directory rather than guessing its location:

$ pkg-config monodoc --variable=sourcesdir
/usr/lib/monodoc/sources

The output is host-specific. Copy only the three matching files there, and reach for sudo only for this installation step:

$ source_dir="$(pkg-config monodoc --variable=sourcesdir)"
$ sudo cp /tmp/my-library-build/my-library.source \
    /tmp/my-library-build/my-library.tree \
    /tmp/my-library-build/my-library.zip \
    "$source_dir"

$ sudo rm "$source_dir/my-library.source" \
    "$source_dir/my-library.tree" \
    "$source_dir/my-library.zip"

6. Open and troubleshoot the result

Start monodoc and look for the label from the node element. If it is absent, check the descriptor first: provider must match the format, basefile must match the output prefix, and path must be a known tree node. If the label appears but pages fail to open, rebuild from the original XML or other source directory and inspect the assembler output for malformed input.

Remember that mdassembler is a compatibility name in this installation. For new automation, prefer mdoc assemble --format=FORMAT --out=PREFIX PATHS, but keep the same provider, basefile and path rules; the older switches remain useful when following documentation that explicitly names mdassembler.