[boost] docca: C++ Documentation XSLT library

Subject: [boost] docca: C++ Documentation XSLT library
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2016-09-09 13:22:51

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"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:variable name="namespace" select="'ripple::'"/>
  <xsl:include href="../include/docca/doxygen.xsl"/>
</xsl:stylesheet>

Above is the file you provide, while include/docca/doxygen.xsl is
provided by docca (This is very much a work in progress).

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?
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?
4. Are these the right tools for the job?
5. Is there anyone out there who is fairly knowledgeable with XSLT and
Boost.Book / QuickBook?

Disclaimer: I am by no means an expert at either Boost.Book,
Quick.Book, XSLT, or bjam. My only experience with these tools is
recently, to put the Beast repository together.

-- 
Follow me on Github: https://github.com/vinniefalco