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-15 17:01:18

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.

> So, to provide a working view of documentation *in draft*, I have resorted to putting a skeleton
> Boost tree
> into my DropBox and pasting in the doc/html/ folder into the right place for the library.  This
> still requires one to also paste in the folder example contents (and indeed /include/boost folder)
> if these are references (good practice).
>
> Although this works, I am not entirely happy doing this and suspect it would be better for each
> /html/ folder to be self-contained, at least as far as style sheets and the Boost logo and various
> navigation and other icons.

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, so I'd rather do that than edit the raw html.
(And being able to freely choose the tools and source formats that fit
my library without having to engage the entire boost community in
never-ending bike-shed discussions is one reason I'm so keen on
modularization. ;-)

> Links to other boost libraries is done by Quickbook using a special @boost: type of link.  This
> assumes the existence of the Boost tree as well, unless it could be made to reference items in
> boost.org.
>
> (It would be nice if these relative links could be at least reduced so that the style sheets and
> logo and icons are right?)
>
> In the case of Python, a brief glance suggest that the appearance come from the use of a local
> rather skeletal boost.css rather than boostbook.css.  .  It might be possible to change this to give
> a uniform appearance? Some parts like tutorial are written using Quickbook toolchain and look
> 'normal'.
>
> Paul
>
> PS It is sad that on github, clicking on the index.html file shows the raw html, not what you see
> using a browser. There is a github.io bit of javascript, but it is very partially successful :-(

Yes. github supports some automated website generation (Jekyll,
notably), but given the low-frequency of content changes in Boost.Python
I'd be happy to do the html generation on my end, using a few parameters
to fine-tune things.

Still, my original question remains: what is the interface that the
Boost website integration requires from library documentation ? What
documentation files need to be present in a given Boost library, and
what (if any) are the requirements on their content ?
What is the the exact process used to generate the Boost.org website
from library docs ? How can I run that locally to validate my changes to
my library docs ?

Thanks,
        Stefan

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