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

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 25 August 2015 09:50 To: boost@lists.boost.org Subject: Re: [boost] [iterator] Regenerating the iterator docs

On Mon, Aug 24, 2015 at 9:06 PM, Edward Diener 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 +44 (0) 1539 561830