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

Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-08-25 10:08:06

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey Semashev
> Sent: 25 August 2015 09:50
> To: boost_at_[hidden]
> Subject: Re: [boost] [iterator] Regenerating the iterator docs
> 
> 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.

Looks a good job to me - though it's difficult to check that nothing has been altered in the
process.

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

I agree - mainly because QuickBook  version is maintainable.

It would be even more maintainable if it used Doxygen-syntax comments to ensure that the synopses
are the same as the real code, even if there is maintenance work done on the header files.  This
would also allow an automatic index to be prepared with no extra effort.

But this would mean copying the 'requirements' and 'effects' information into the header files by
hand. A new branch (new_docs?) would be safest?

I'm willing to tackle this if people think it worthwhile.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]