Export mdoc XML to Microsoft Docs with mdoc-export-msxdoc

mdoc-export-msxdoc turns one or more Mono mdoc documentation directories into a Microsoft XML Documentation file. That is the same format the C# compiler's /doc option produces, and this guide uses the version from monodoc-base 6.8.0.105+dfsg-3.6ubuntu2, as installed on this machine.

Allow about fifteen minutes. You need a shell, the monodoc-base package, and a directory containing valid mdoc XML. The examples read documentation and write a new file in the current directory: they do not install anything, edit the source XML, or need elevated privileges.

1. Check the installed command

Confirm which executable will run and record the package version. These are ordinary, read-only commands:

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

2. Check the input layout

The exporter expects a directory in Mono documentation format, not a single type XML file. At its root, a normal input has index.xml, namespace files named ns-*.xml, and directories containing type files:

$ find /path/to/mdoc -maxdepth 2 -type f -print
/path/to/mdoc/index.xml
/path/to/mdoc/ns-Example.xml
/path/to/mdoc/Example/Widget.xml

index.xml records assemblies, namespaces and types. A type file holds the type metadata and its Docs elements. The exporter reads those files and turns documented types and members into Microsoft member identifiers such as T:Example.Widget and C:Example.Widget.

Do not point the command at a random directory of unrelated XML. If index.xml is missing, the command exits with status 1 and reports that it could not find that file. Fix the input path or generate the mdoc tree first; sudo will not repair an incomplete input.

3. Export to one named file

Use -o or --out with a destination path when a build or review step needs one predictable file:

$ mkdir -p /path/to/build
$ mdoc-export-msxdoc --out=/path/to/build/Example.xml /path/to/mdoc

Logging can vary by package version, so the useful checks are the exit status and the existence of the output file:

$ test -s /path/to/build/Example.xml && echo 'export created a non-empty file'
export created a non-empty file
$ sed -n '1,24p' /path/to/build/Example.xml
<doc>
    <assembly>
        <name>Example</name>
    </assembly>
    <members>
        <member name="T:Example.Widget">

4. Send the result to standard output

Use -o - when another command should consume the XML, or when you want to inspect the conversion without creating a file:

$ mdoc-export-msxdoc -o - /path/to/mdoc > /tmp/Example.xml
$ test -s /tmp/Example.xml && echo 'standard-output export captured'
standard-output export captured

The hyphen is significant: it tells the exporter to write XML to standard output. Shell redirection creates or truncates /tmp/Example.xml before the exporter even runs, so do not point it at a valuable existing path in a blind command. If the export fails, check the command status before treating the redirected file as usable:

$ mdoc-export-msxdoc -o - /path/to/mdoc > /tmp/Example.xml
$ status=$?
$ printf 'export status: %s\n' "$status"
export status: 0

5. Let the exporter create per-assembly files

Omit -o when the input holds assemblies that should become separate files. The command writes into the current working directory, using the values in //AssemblyInfo/AssemblyName from the documentation, and also creates namespace summaries:

$ mkdir -p /path/to/exported
$ cd /path/to/exported
$ mdoc-export-msxdoc /path/to/mdoc-one /path/to/mdoc-two
Example.xml
Other.xml
NamespaceSummaries.xml
$ find . -maxdepth 1 -type f -printf '%f\n'
Example.xml
Other.xml
NamespaceSummaries.xml

This mode suits a collection of assemblies, but the current directory matters: make a dedicated output directory first so an export cannot mix with unrelated build artefacts. If two inputs produce the same assembly name, resolve that collision before exporting into a shared directory, because a name collision makes it unclear which result is authoritative.

6. Inspect and diagnose the result

Microsoft XML Documentation normally has a doc root, an assembly name and a members collection. Inspect the structure with an XML-aware tool if one is installed, or use a small read-only check:

$ grep -E '<(doc|assembly|members|member)( |>)' /path/to/build/Example.xml
<doc>
    <assembly>
    <members>
        <member name="T:Example.Widget">
        <member name="C:Example.Widget">

An empty or missing member list usually means the input tree did not contain the documentation you expected, rather than that the exporter needs a special flag. Recheck index.xml, the namespace and type paths, and the Docs elements. If a source file is malformed, validate or repair the mdoc tree with the Mono documentation tools before exporting again.

The installed help also lists -q for reduced console logging. The installed manual documents -o, help options, and the positional directories, so base automation on the documented interface and treat logging as non-essential. The XML file and the process exit status are the reliable outputs to test.