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

Subject: Re: [Boost-docs] interface between library documentation and Boost website
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2015-07-17 18:07:28

Hello,

so in order to make some progress, I have followed the typical github
process for setting up a project homepage for my own Boost.Python repo
(i.e., created a gh-pages branch). With some minor adjustments to image
and stylesheet locations to make the Boost.Python docs self-contained, I
was able to generate this:

http://stefanseefeld.github.io/boost.python/doc/index.html

I would ultimately like to do the same for the upstream project at
https://github.com/boostorg/python/, but first need to understand the
process so I can avoid introducing bugs. At least for Boost.Python,
where documentation changes are rare, I think this mechanism may just be
enough.

On 15/07/15 01:38 PM, Robert Ramey wrote:
> On 7/15/15 10:01 AM, Stefan Seefeld wrote:
>
>> 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

Comparing the above docs with
http://www.boost.org/doc/libs/1_58_0/libs/python/doc/index.html, I
notice a couple of differences, suggesting that the process of merging
the Boost.Python docs into the Boost.org website isn't quite as
straight-forward as dropping in some html files into the appropriate
place(s). So I'm asking again: what is the precise process that is being
used to convert library-specific docs into the Boost documentation tree ?

>
> How can I run that locally to validate my changes to
>> my library docs ?
>
> You can, and I do.

Same question here: How exactly ?

Many thanks,
        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...