docca: C++ Documentation XSLT library
Hi. When I developed Beast for Boost.Asio
(https://github.com/vinniefalco/Beast), I lifted the xsl transforms
from Boost.Asio (thanks Chris!) and adapted them. These scripts take
the output of Doxygen and transform them into Boost.Book code (or
QuickBook code or whatever its called). In other words, it creates a
file called reference.qbk. This file is included in the documentation,
which gets processed through a Jamfile to produce the HTML
documentation that you see here:
http://vinniefalco.github.io/beast/index.html
This is great, and I am using the same system for my new key/value
database engine (https://github.com/vinniefalco/NuDB/). The problem is
that now I want to start another project and use the same
documentation, but there is a considerable amount of copying going on
here. The entire reference.xsl file is copied and placed in the new
project:
https://github.com/vinniefalco/NuDB/blob/master/doc/reference.xsl
This file has to be edited significantly because it has references to
project-specific namespaces, prefixes, and various other annoying
minutiae.
Therefore, I have started a new project called "docca:"
https://github.com/vinniefalco/docca
This project aims to refactor my variant of Boost.Asio's reference.xsl
file so that it can be re-used in other projects. The procedure would
be to create your own empty .xsl file, and include docca's xsl file
after defining some variables. For example:
<?xml version="1.0" encoding="utf-8"?>
On 9 September 2016 at 19:22, Vinnie Falco
Hi. When I developed Beast for Boost.Asio (https://github.com/vinniefalco/Beast), I lifted the xsl transforms from Boost.Asio (thanks Chris!) and adapted them. These scripts take the output of Doxygen and transform them into Boost.Book code (or QuickBook code or whatever its called). In other words, it creates a file called reference.qbk. [...] By this point many of you have fallen asleep, XSLT is a great cure for insomnia. If you're still awake you're probably very excited at the prospects of a turn-key solution for making great looking docs out of Javadoc comments in your C++ headers so I'll move right on to the questions:
1. Is there already a system for doing this?
Doxygen XML to Quickbook? I don't think so, but see below
2. If not, is there any interest in such a system? Is this project worth the effort? 3. Is this approach viable? Or is there a different approach?
Long time ago, I also picked Boost.Asio XSLT and based on that I developed preliminary documentation generator for Boost.Geometry. Eventually, we found it is very complex and difficult to maintain, so Barent Gehrels developed bespoke Doxygen XML processing tool written in C++ and dedicated for Boost.Geometry. Here is the full story: http://barendgehrels.blogspot.com/2010/12/doxygen-and-quickbook.html http://www.boost.org/doc/libs/1_61_0/libs/geometry/doc/html/geometry/aboutdo... However, Boost.Asio approach seems like the one with potential to become a Boost general purpose converter usable for other/all libraries. Despite I no longer work on the XSLT-based converter for Boost.Geometry, I give big thumbs up to your efforts. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net
participants (2)
-
Mateusz Loskot
-
Vinnie Falco