Assemble MonoDoc Documentation with mdassembler

You will finish with a MonoDoc documentation bundle and the small XML source file that tells monodoc where to display it. The workflow uses mdassembler for the legacy command name, checks the installed implementation, and keeps installation separate from the build.

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 requires elevated privileges. This guide does not edit package-managed documentation or publish a new system-wide source until the generated files have been checked.

1. Check which assembler you have

The name mdassembler is obsolete in the installed manual and has been superseded by mdoc assemble. On this machine, the command is provided by 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 host instead of assuming that 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

Checkpoint: if the command is missing, stop here and install the distribution package through your normal change process. Do not copy a binary from an unrelated Mono installation into /usr/bin.

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. For normal Mono API XML produced by monodocer, use --ecma. For a directory of text files, use --simple; for man pages, use --man.

Choose a prefix without a filename extension. The assembler appends .tree and .zip to that prefix according to the documented interface. 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 that 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 use the same prefix. If either test fails, stop and read the assembler's diagnostic. Do not copy a partial result into the system sources directory.

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

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>

The basefile value is not a path and must not include an extension. The path value connects the source to the tree node. If you use a different parent or path, inspect MonoDoc's installed monodoc.xml for valid node names. A typo here can leave a perfectly good bundle invisible in the browser.

Checkpoint: confirm that all three files share the same basename:

$ 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 without 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 use 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"

Warning: this changes shared system state. If files with those names already exist, stop and make a backup before replacing them. To recover a bad installation, restore the three backups and restart monodoc. If no backups exist, remove only these exact files from the reported sources directory, then rebuild and reinstall; do not use a wildcard:

$ 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.