I'm currently searching for a proper workflow for combining doxygen and dokuwiki in a useful way.
Right now our users in our private wiki are documenting software packages with overview pages and tutorials. Especially in the tutorials we use the code syntax for displaying important workflows for using our software packages. This results in good looking code blocks with syntax highlighting.
But the code syntax comes with some drawbacks:
- the code has to be manually updated
- the code lacks references (links) to the original source code / documentation of individual functions, enums, ...
Doxygen on the other hand handles this very well. A typical tutorial in doxygen would be a custom page, where code is either referenced (a link to the generated documentation of the element) or included with a snippet (a special area in the source code that is marked with doxygens syntax). Especially the snippet is useful. It also renders links inside the source code to the individual definitions. If enabled these definitions also feature a link to the source code itself. Thereby a nice way for exploring the code is created.
The way doxygen does this involves parsing the source code - I think this is something that we can not implement for dokuwiki in a reasonable way.
Possible Solutions
- Creating tutorials in doxygen and linking from dokuwiki to the doxygen pages (this breaks our goal of using dokuwiki as our central documentation that is easy/fast to edit)
- Integrating the Doxygen syntax into dokuwiki
- converting the doxygen documentation to dokuwiki pages
Option 1 would be easy - just host the generated doxygen documentation somewhere (gitlab, github) and implement links in the wiki pages. But the user would have to leave dokuwiki often.
Option 3 has been already tried https://github.com/tgeijten/dokugen/. But I'm not really satisfied with the result. Especially my use case where the source code of snippets should be explorable can't be implemented right now. Inserting pages in the file tree also is quite "brutal". I also think that this is not easy to do for the average dokuwiki user: working in the file tree (e.g. deleting old pages) should only be done in exceptional cases.
I think option 2 is the preferred way. My idea right now is to create a plugin for dokuwiki that:
- implements a syntax plugin where the doxygen syntax can be used
- renders the doxygen syntax to html
- integrates the html into the wiki page
- changes the URLs in the html from doxygen so that they point to a configurable doxygen instance of the documentation
Workflow Prototype
When the doxygen syntax is matched, the plugin should obtain the source code from a VCS (e.g. git). If the source code is already available on the system, it should check for updates. Then it should insert doxygen pages for each syntax match in configurable directory (e.g. "pages"). To make the HTML output of the page embeddable, we need to strip the header and footer from the page. In a test project I did this by implementing custom header.html, footer.html, layout.xml, and stylesheet.css files. After compiling the pages, the dokuwiki plugin should insert an iframe in the output of the wiki page including the rendered doxygen page.
Challenges
- cloning and updating of the source code can be fragile (permissions for git; which repository to use for which syntax match; what happens if multiple pages use multiple versions of one repository?)
- cloning and building the documentation can take a while (maybe run it through the taskrunner - but then we have no render output when the page is rendered...)
- where do we store the cloned repository? (some repositories are huge, have lots of files, ...)
All in all I think that this is too much to implement inside dokuwiki. Most doxygen documentations are built through a CI/CD pipeline - integrating the build process into dokuwiki on a small web server is probably a bad idea. But I think that an integration for better code documentation is something that should be looked into for dokuwiki. Maybe someone reading this has more insight into tools like doxygen. Maybe there is a way to directly use the parser from doxygen and output the html from a precompiled version of the documentation? We could push the precompiled version of the documentation from a CI/CD pipeline to dokuwiki, so dokuwiki doesn't have to build the complete documentation / check for updates.
Relevant links / discussions