Export Monodoc XML to HTML with monodocs2html

monodocs2html looks like the old exporter but is actually a compatibility shim, so its own help text will send you chasing options that do nothing.

On this machine monodocs2html delegates to mdoc export-html. Allow about fifteen minutes for a first export.

• You need: the monodoc-base package, a readable documentation tree, and a separate output directory.
• No sudo needed to read documentation or write into a directory you own.
• Out of scope: this guide covers exporting and templating. It does not create Monodoc XML, install documentation, or alter a web server.

1. Confirm the installed implementation

Check the command and package before relying on examples copied from an older Mono installation:

$ command -v monodocs2html
/usr/bin/monodocs2html
$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-base
monodoc-base 6.8.0.105+dfsg-3.6ubuntu2

The local manual describes the historical interface, including -source:SOURCE_DIR and -dest:DEST_DIR. The installed wrapper translates those options to the newer mdoc export-html interface, so its -help output shows modern mdoc usage rather than the legacy option names.

• -V and -version are accepted by the wrapper but ignored, so they will not print a version here.
• -onlytype:TYPE is also ignored. A run that accepts it is not proof it filtered the export.

2. Check the source tree

The source directory must be the base of a Monodoc documentation collection: an index.xml file, one XML file per namespace, and a directory per namespace containing the type XML files.

Inspect the tree without changing it. Replace the placeholder with the real path:

$ SOURCE_DIR='/path/to/monodoc-xml'
$ test -r "$SOURCE_DIR/index.xml" && echo 'index.xml: readable'
index.xml: readable
$ find "$SOURCE_DIR" -maxdepth 2 -type f -name '*.xml' -print | sort | head

An empty find result or a missing index is a source-layout problem, not a reason to add more exporter options. Stop and locate the directory that actually holds the collection root. If the files belong to another user or a package-managed location, ask for read access rather than making broad permission changes.

3. Export to a new destination

Choose a destination that does not contain an export you need to keep. The command creates HTML using the default html extension:

$ DEST_DIR="$PWD/monodoc-html"
$ test ! -e "$DEST_DIR" || { echo "Refusing existing destination: $DEST_DIR"; exit 1; }
$ monodocs2html -source:"$SOURCE_DIR" -dest:"$DEST_DIR"
$ find "$DEST_DIR" -type f -name '*.html' -print | head

The wrapper passes the source directory to mdoc export-html and maps the destination to --out. A non-zero exit status means the export was not a success, even if a few files appeared. Check the error, fix the source or destination, and use a fresh output directory for the next attempt.

4. Verify the generated files

Check that output exists, is non-empty, and has the extension you intended:

$ find "$DEST_DIR" -type f -name '*.html' -size +0c -print | head
$ test -s "$DEST_DIR/index.html" && echo 'index.html: non-empty'
index.html: non-empty

Open a representative file with a browser or check its first lines. Generated pages are documentation output, not a guarantee your site stylesheet matches the template, so look for the collection or page title and a link to the expected type or member before publishing the directory.

5. Change the file extension when needed

Pass -ext:EXTENSION if another extension is required by an existing documentation site:

$ ALT_DIR="$PWD/monodoc-xhtml"
$ monodocs2html -source:"$SOURCE_DIR" -dest:"$ALT_DIR" -ext:xhtml
$ find "$ALT_DIR" -type f -name '*.xhtml' -print | head

The extension value only names created files. It does not convert the document format by itself, and it does not update links in files already generated. Keep each extension in its own destination so an old HTML tree cannot be mistaken for the new export.

6. Inspect or supply an XSLT template

To see the built-in template, write it to a temporary file or standard output. This is read-only with respect to your source tree:

$ monodocs2html -dumptemplate > /tmp/monodocs2html-default.xsl
$ test -s /tmp/monodocs2html-default.xsl && echo 'template: non-empty'
template: non-empty

A custom template is an XSLT file passed with -template:FILE. The input page has fields such as CollectionTitle, PageTitle, Summary, Signature, Remarks, Members, and Copyright. The output also relies on CSS class names including PageTitle, MemberName, MembersListing, and TypesListing.

Copy the dumped template to a project-controlled file and make one small change first. Export to a new destination, then compare a representative page with the default export. Keep the original template until the new output has been checked: there is no automatic undo for files overwritten in a destination.

7. Recover from a failed or unwanted export

If an export failed in a newly created destination, leave the source tree alone and remove only that disposable destination, after checking its exact path:

$ test "$DEST_DIR" = "$PWD/monodoc-html" || exit 1
$ rm -rf -- "$DEST_DIR"
$ test ! -e "$DEST_DIR" && echo 'temporary export removed'