Doxygen Plugin for DITA-OT

This is a DITA-OT Plug-in used to auto-create valid DITA-based Doxygen documentation. The initial source of the documentation can be generated directly using the Doxygen XML. The XML file can be added to the source and processed as if it had been written in DITA.

Table of Contents

• Background
• Install
  • Installing DITA-OT
  • Installing the Plug-in
• Usage
• License

Background

Doxygen is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields.

Sample doxygen

namespace transport
{
    /** Mountain bike implementation of a `Bicycle`.
     *
     * MountainBike is an implementation of a Bicycle
     * providing a bike for cycling on rough terrain. Mountain bikes
     * are pretty cool because they have stuff like **Suspension** (and
     * you can even adjust it using SetSuspension). If you're looking
     * for a bike for use on the road, you might be better off using a
     * RacingBike though.
     *
     * @ingroup mountainbike
     */
	class MountainBike : public Bicycle
	{
	public:
		/** Set suspension stiffness.
		 * @stiffness the suspension stiffness.
		 *
		 * SetSuspension changes the stiffness of the suspension
		 * on the bike. The method will return false if the stiffness
		 * could not be adjusted.
		 *
		 * @return true if the suspension was adjusted successfully,
		 *         false otherwise.
		 */
		bool SetSuspension(double stiffness);

Sample DITA Output

Install

The DITA-OT doxygen plug-in has been tested against DITA-OT 3.x. The plugin requires the XSLT 3.0 support found in the Saxon9.8HE library, so the mimimum DITA-OT version is therefore 3.3. It is recommended that you upgrade to the latest version.

Installing DITA-OT

The DITA-OT doxygen plug-in is a file reader for the DITA Open Toolkit.

• Full installation instructions for downloading DITA-OT can be found here.

  1. Download the dita-ot-4.2.zip package from the project website at dita-ot.org/download
  2. Extract the contents of the package to the directory where you want to install DITA-OT.
  3. Optional: Add the absolute path for the bin directory to the PATH system variable.

  This defines the necessary environment variable to run the dita command from the command line.

curl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip
unzip -q dita-ot-4.2.zip
rm dita-ot-4.2.zip

Installing the Plug-in

• Run the plug-in installation commands:

dita install https://github.com/jason-fox/fox.jason.passthrough.doxygen/archive/master.zip

The dita command line tool requires no additional configuration.

---

Usage

To do generate Doxygen XML set GENERATE_XML to YES.

The XML output consists of an index file named index.xml which lists all items extracted by doxygen with references to the other XML files for details. The structure of the index is described by a schema file index.xsd. The Doxygen source should be concatenated into one single XML file using the instructions found in the XSLT file combine.xslt.

Once the source XML has been created, add it to the *.ditamap and mark it for doxygen processing, by labelling it with format="doxygen" within the *.ditamap as shown:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    ...etc
    <appendices toc="yes" print="yes">
      <topicmeta>
        <navtitle>Appendices</navtitle>
      </topicmeta>
      <appendix format="dita" href="topic.dita">
        <topicref format="doxygen" type="topic" href="doxygen.xml"/>
      </appendix>
   </appendices>
</bookmap>

The additional file will be converted to a *.dita file and will be added to the build job without further processing. Unless overridden, the navtitle of the included topic will be the same as root name of the file. Any underscores in the filename will be replaced by spaces in title.

License

Apache 2.0 © 2020 - 2024 Jason Fox