doxycode Plugin

This plugin implements syntax-highlighted code snippets with cross referencing to external Doxygen documentations. It is designed for users who want to integrate detailed code analysis into their documentation.

Doxycode leverages Doxygen's ability to parse and cross-reference code by exporting the content of the code snippets as source files and executing a Doxygen build in the background. It then parses the XML output of Doxygen as HTML that mimics the style of DokuWiki's default code blocks. Doxygen tag files from existing documentations are used during the build process for the cross-references. Doxycode extracts the detected references from the XML output and creates links inside the code snippets to the corresponding documentation.

This integration offers a seamless blend of DokuWiki's structured documentation format with the analytical depth of Doxygen.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Using doxycode involves the following steps:

• Creating a tag file configuration (in the admin interface)
• Downloading tag files
• Creating a code snippet that uses the tag file

This section only shows how to use doxycode as a user. Refer to the configuration section for an explanation on how to setup the tag file configuration.

Basic syntax:

<doxycode tagfiles="tag_name1 tag_name2" [linenumbers] [language="c"] [render_task] [filename.c]>
#include "header.h"

...
</doxycode>

Browsing the available tag files on a DokuWiki instance is made easy with the doxycode toolbar entry. When clicked a dialog opens that loads the list of available tag files via AJAX. The user can select the tag files to be used here.

The tag file selector dialog tries to find an existing doxycode syntax near the cursor position in the editor. If an existing syntax could be found it loads the selected tag files into the results.

When inserting the list of selected tag files it either replaces the tag file list in the existing syntax or inserts a new doxycode syntax at the cursor position in the editor.

This section covers the configuration options for administrators.

These configuration parameters can be set through the configuration manager.

For cross-referencing Doxygen documentations tag files are needed. In this admin interface tag file configuration entries can be created.

Tag files can be loaded onto the server in the following ways:

• Uploading a file (the filename will be used for creating the entry - be careful existing tag files might be overwritten if the wrong filename is used)
• Automatically downloading tag files: insert a new entry with the remote URL and the update period set
• Uploading from CI/CD: insert a new entry without the remote parameters set

By default all Doxygen builds are executed in the renderer. When using large tag files the build might take so long that the page times out. Doxycode implements a 'TaskRunner' feature for solving this that can be enabled globally for specific tag files or in the syntax for specific code snippets. Doxycode will then save information about the code snippets and execute the Doxygen build when DokuWiki's taskrunner process is executed.

Doxycode bundles all snippets with the same Doxygen configuration in one 'task'. Each code snippet is called a 'job' in this context. Bundling multiple jobs in one task decreases the build time. The information about the tasks and jobs are saved in SQLite tables with the helper of the sqlite plugin. If the plugin is not installed doxycode falls back to direct build execution during rendering.

Optional requirements: This plugin optionally uses the following additional components that can be installed separately:

• sqlite

When a code snippet is build through the TaskRunner the page will contain a message informing the user about it. If JavaScript is available the page will periodically request the build state via AJAX. After the build job finished the page will dynamically load the snippet via AJAX.

The main way for obtaining tag files is through remote configurations where the tag files are available publicly and periodically downloaded by doxycode. For private projects where the source code and the documentation are not public, doxycode offers the possibility of uploading tag files from CI/CD pipelines via a remote API call to the DokuWiki instance.

The upload is implemented in a python script that is available here: https://github.com/lprobsth/doxycode_py_upload

It either uses the old XML RPC API or the newer JSON RPC API. The script will select the API interface based on the credentials provided to the script:

• XML RPC API for username/password
• JSON RPC API for API tokens

Refer to https://github.com/lprobsth/doxycode_py_upload/tree/main?tab=readme-ov-file#usage for how to use the python upload script.

In the following sections some basic examples for CI/CD uploads are given.

Create the CI/CD variables for the credentials either for the group, user or project. Please note that the variables are not considered secure - they might be leaked into logs or obtained through the console. GitLab works on a credential provider for the GitLab runners. But for now the CI/CD variables have to be used.

Example pipeline:

image: python:3-alpine

pages:
  script:
  - apk update && apk add doxygen graphviz ttf-freefont git
  - pip install dokuwikixmlrpc
  - git clone https://github.com/lprobsth/doxycode_py_upload.git
  - doxygen docs/doxygen.conf
  - ./doxycode_py_upload/upload_tag_file.py docs/canopen_dictionary_lib.xml
  - mv docs/html/ public/
  - mv docs/*.xml public/
  artifacts:
    paths:
    - public
  only:
  - main

Here the tag file 'canopen_dictionary_lib.xml' is uploaded and the doxygen documentation is published to GitLab Pages.

The source code of the plugin is available at GitHub: https://github.com/lprobsth/dokuwiki-plugin-doxycode.

Please report issues and feature requests in the bug tracker at https://github.com/lprobsth/changes/dokuwiki-plugin-doxycode

The following list only serves as a quick overview of the most important issues and ToDo's.

• Merge pull request #9 from lprobsth/dev/lprobsth_enhance (2024-02-16 17:29)
• handle corrup entries in the task table better (2024-02-16 17:28)
• Update plugin.info.txt (2024-02-16 17:17)
• Merge pull request #8 from lprobsth/dev/lprobsth_enhance (2024-02-16 17:10)
• update plugin info (2024-02-16 17:07)
• handle build fail gracefully (2024-02-16 17:07)
• make doxygen executable configurable (2024-02-16 17:07)
• Merge pull request #7 from lprobsth/dev/lprobsth_enhance (2024-01-21 16:58)

• Implement replacing the names of tag files after a tag file was renamed in the admin interface.
• Implement global setting for executing builds through the task runner.
• Implement function for cleaning the sqlite tables.
• Add more CI/CD examples.
• Add technical background (what are tag files?) to the wiki page.
• Implement detailed output of log if doxygen build fails (currently it just displays a simple message).
• Add option for embedding externally hosted code.
• Add taglist syntax to the usage section in the wiki page.
• Implement better taglist syntax for listing all available tag files.