![]() So what does the end result actually look like?Īctually, really nice! Here’s some of our documentation in our test instance of Confluence. This was resolved with a little extra code in the form of two extension methods: We had a few small problems initially with 5xx and 4xx errors, which turned out to be issues with properly escaping and URL encoding the XHTML that was sent along with the request. On successful generation, the task uploads the file as Build artifact so that it can be. Build task The task, named Documentation (Doxygen), uses Doxygen and PdfLatex tools installed on the Build Agent machine to generate the documentation from source code in your repository. Since it’s an internal tool, we favour the simplicity of using an API token for authentication, along with basic auth. A new 'Documentation' hub under Code to view the documentation. After reading the REST API documentation for Confluence, we find that we need to POST the XHTML page to the following Content URL: So much so that we take the approach of picking off small parts at a time until we support enough of the schema to be useful. This part isn’t particularly hard, but a little time consuming since the Doxygen schema is a little large. This creates a folder full of XML, containing the information in all the comments, but without the presentation details.įrom here, we use some C# to parse through the XML and combine it with the XHTML templates, to produce a series of XHTML storage format Confluence pages. ![]() The first job is to run the Doxygen tool over our Mako source code, but instead of outputting HTML, we output XML instead. Upload the XHTML using Confluence REST APIs to build the documentation.Convert the Doxygen XML output to XHTML Storage format.So there’ll be two main parts the tool will need to tackle: Specifically, we’ll look at the following path:ĭoxygen > XML output > Doxygen-To-Confluence tool > XHTML Storage Format > Confluence So the plan is to write a command line application which will convert and upload our Doxygen output to Confluence. Neither does it seem that there are any tools that do the job too.Įnter the Shed and a coding project! Writing a Doxygen to Confluence Tool Since Confluence has good search capabilities, it got me wondering if we could upload the Doxygen output to Confluence.įrom some googling, it seems that Doxygen has a couple of output types, and Confluence has a few import formats, but unfortunately no intersection. If you’re a Mako customer, you’ll be aware that we’re currently moving our documentation over to a new Confluence site. There’s some options that Doxygen provide to improve the experience, but we thought we’d look at this as an opportunity to see how we could do better more generally. No use then for looking for concepts rather than types. Specifically, the standard search will simply try to match the start of an indexed symbol. Indeed, Doxygen’s standard search mechanism is not very good. This all sounds great, but some feedback that we hear is that although the documentation is good, it’s let down by the ability to search and find it.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |