📖 render-docs

This repository contains the code for the render-docs command line tool. The purpose of it is to create markdown documentation from doxygen compatible code comments in C and C++ code. The benefit of maintaining API documentation along with the code itself is that you get inline documentation tooltips by IDEs that support that plus the chance of documentation getting out of sync is lower as code maintainers have it in front of their eyes when making changes. The tool uses a fork of moxygen to parse the XML output generated by doxygen.

💻 Usage

Usage: render-docs [options] <source folder> <target folder>

CLI tool to generate markdown documentation from C++ code using Doxygen

Arguments:
  source                       Source folder containing the .h files
  target                       Target file / pattern for the markdown documentation.

Options:
  -V, --version                   output the version number
  -e, --exclude <string>          Pattern for excluding files (e.g. "*/test/* internal.h")
  -c, --include-cpp               Process .cpp files when rendering the documentation.
  -a, --access-level <string>     Minimum access level to be considered (public, private) (default: "public")
  -s, --show-access-modifiers     how access modifiers in documentation
  -f, --fail-on-warnings          Fail when issues in the documentation are found (default: false)
  -d, --debug                     Enable debugging mode with additional output. (default: false)
  -r, --resolve-issues [api-key]  Automatically fix issues in the documentation. (default: false)
  -h, --help                      display help for command

You can also specify single files as input so only those will be processed (e.g. render-docs Folder.h ./api.md)

If the target path contains %s one file will be generated per class. In that case %s will be replaced with the class name.

Tip

If you don't want to render any output but only want to check the documentation for completeness, you can omit the second argument and add the -f option (e.g. render-docs Folder.h -f).

Tip

⚠️ Experimental: You can leverage OpenAI to help resolving issues in your documentation (e.g. undocumented functions). To do so, you can omit the second argument and add the -r option (e.g. render-docs Folder.h -r). For this to work you will have to create an OpenAI API key and provide it to this tool. You can do that either by adding it to the -r option (e.g. -r fklj343-sdfjl-34) or pass it as environment variable OPENAI_API_KEY (e.g. OPENAI_API_KEY=fklj343-sdfjl-34 render-docs UFile.h -r).

Options Explained

--version Prints the version of this command / package.
--exclude Use this when certain files or folder inside the source folder should not be processed (e.g. -e */test/* */node_modules/*).
--include-cpp It's good practice to do the class and function declarations in the .h file and thus also add the documentation there. However, if you happen to have code documentation also in .cpp files enabling this option will process those files too.
--access-level Allows to specify which class members to filter out in the documentation. If you specify private all members will show up in the documentation. If you set it to protected only the private members will be filtered out. When set to public only public members will be processed.
--show-access-modifiers Includes the access modifier in function documentation. e.g. public int getTemperature() when set, vs. int getTemperature() when not set.
--fail-on-warnings The command will print out missing code documentation and issues in existing documentation. This allows to achieve 100% documentation coverage.
--debug Enable this option to get additional output from the tool. This allows to debug in case you get unexpected output from the command.
--help Displays usage information.

⚙️ Installation

The easiest way is to use npm: npm install github:arduino/render-docs --no-save --silent You can then call npx render-docs to run the command. Alternatively you can install the tool globally using npm install -g github:arduino/render-docs and then run it with render-docs. A local installation is advisable whenever possibe as it avoids any version conflicts with this tool and its dependencies that may be used by other tools too.

Important

On Linux you will need to manually install the depenencies required by doxygen which is used under the hood. To do so run the following commands:

# Import LLVM GPG key without using apt-key
wget -q -O - https://apt.llvm.org/llvm-snapshot.gpg.key | gpg --dearmor -o /usr/share/keyrings/llvm-archive-keyring.gpg

# Add the LLVM repository with the GPG keyring
echo "deb [signed-by=/usr/share/keyrings/llvm-archive-keyring.gpg] http://apt.llvm.org/jammy/ llvm-toolchain-jammy-15 main" | sudo tee /etc/apt/sources.list.d/llvm.list > /dev/null

# Update the package lists
sudo apt-get -qq update

# Install libclang and other necessary packages
sudo apt-get install -y libclang1-15 libclang-cpp15

🧑‍💻 Developer Installation

The easiest way is to clone the repository and then run the tool with node index.js. For debugging purposes there is a VSCode launch config available.

🐛 Reporting Issues

If you encounter any issue, please open a bug report here.

💪 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

🤙 Contact

For questions, comments, or feedback on this package, please create an issue on this repository.