Re: [boost] [iterator] Regenerating the iterator docs

Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2015-08-25 06:47:02

On 8/25/2015 4:50 AM, Andrey Semashev wrote:
> On Mon, Aug 24, 2015 at 9:06 PM, Edward Diener <eldiener_at_[hidden]> wrote:
>> I have updated a very small portion of the iterator docs and now I need to
>> regenerate the documentation. Evidently despite iterator having quickbook
>> documentation the actual documentation presented to end-users is created
>> from RST files, python scripts, and make files. But I do not see the process
>> of regenerating the docs explained anywhere so I am wondering if anyone
>> knows how to do it.
>
> FWIW, when I updated Boost.Iterator docs in one of my PRs I only
> updated .qbk. I have no idea what .rst is, how to edit it or generate
> output from it. Also, as I remember when I did the change the .qbk
> docs looked more actual to me, so I figured that .rst was something
> outdated.

Unfortunately whatever changes you made did not appear in any Boost 
release for the end-users unless they manually built the documentation 
using quickbook. We all know what this entails in user-config.jam.

>
> I'd prefer we only keep one copy of the docs, preferably QuickBook,
> and remove the other to avoid the confusion.

I am in agreement with you. But this does mean that the documentation 
format which we distribute as the iterator documentation does change in 
its overall look. The documentation which the end-user sees in the Boost 
1.59 distro is the one generated by the .rst files and process, not the 
one generated by the quickbook files.