Re: [Boost-docs] interface between library documentation and Boost website

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Robert Ramey (ramey_at_[hidden])
Date: 2015-07-15 17:38:38

On 7/15/15 10:01 AM, Stefan Seefeld wrote:
> On 15/07/15 12:44 PM, Paul A. Bristow wrote:
>> This relative linking is an issue for most, if not all, documentation, including that produced by
>> the popular Quickbook toolchain.
>
> True.
>

> Yes, that would solve this particular issue. Still, there are quite a
> number of frameworks available that allow documentation for various
> media (including html and pdf) to be generated from a much simpler to
> author markup formats,

This is a question going back a long way.  The solution was boost book -
derived from docbook.  This uses xslt to generate html, pdf or whatever.
Since, editing boostbook is a pain, several solutions options for that 
have evolved.

a) quickbook generates boostbook from a marked up file.  It has been the 
most frequently chosen option for generating boost documentation.  I 
would say it's been quite successful and the documents created - html 
and pdf have been of good quality.

b) my personal favorite is to use a boostbook xml editor - the one that 
has worked well for me is described here 
http://rrsd.com/blincubator.com/tools_documentation/

c) other options, markdown, doxygen, raw html, I have found to be inferior.

We've sort of decided to not try to impose a common requirement as the 
tools have evolved faster than boost library documentation has. And of 
the work involved just wouldn't be worth it.

> Still, my original question remains: what is the interface that the
> Boost website integration requires from library documentation ?

Not much.  provide one of the following:

a) raw html files generated any way you want
b) boostbook xml files
c) quickbook xml files.

What
> documentation files need to be present in a given Boost library, and
> what (if any) are the requirements on their content ?

My views are described here.  The web page has an opportunity to comment 
but no one has ever done so.  So, I'm going to assume the fairly 
represent the consensus of the community.

> What is the the exact process used to generate the Boost.org website
> from library docs ?

For using boostbook/quickbook - this is described somewhere.  It DOES
work, but it's not totally pain free to setup

How can I run that locally to validate my changes to
> my library docs ?

You can, and I do.

Robert Ramey