Documenting multiple namespaces

Documentation of multiple namespaces may take one of two forms:

• All namespaces may be included in a single documentation file
• Each namespace may be documented in a separate file

An additional factor is whether the built-in HTML formatter or an external formatter is being used.

If the internal HTML formatter is being used, multiple namespaces can be documented in a single documentation file simply by passing multiple namespaces as a list to the document_namespaces command. If multiple output files are desired, then the command is invoked separately for each namespace. In this case, however, there will be no automatic cross-referencing or navigation menus across namespaces.

In the case where an external formatter is being used, single file output may be generated through the use of the -append option to the document_namespaces command:

::ruff::document_namespaces doctools ::some_namespace -output some_namespace.man
::ruff::document_namespaces doctools ::another_namespace -output some_namespace.man -append true

Both namespace are then documented in the same file. Note that some formatters, like doctools, may not be able to process such a combined file.

If separate output files are desired, separate files can be generated for each namespace. Here the formatter in use has to combine these into a single documentation set. Refer to the documentation for the appropriate formatting tool for information on how to accomplish this.