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-26 07:17:55

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey Semashev
> Sent: 26 August 2015 12:07
> To: boost_at_[hidden]
> Subject: Re: [boost] [iterator] Regenerating the iterator docs
> 
> On 26.08.2015 13:41, Paul A. Bristow wrote:
> >> -----Original Message-----
> >> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
> >> Edward Diener
> >> Sent: 25 August 2015 18:01
> >> To: boost_at_[hidden]
> >> Subject: Re: [boost] [iterator] Regenerating the iterator docs
> >>
> >> On 8/25/2015 12:56 PM, Daniel James wrote:
> >>> On 24 August 2015 at 19:06, 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.
> >>>
> >>> When I've changed them, I think I just used rst2html with the rst
> >>> files that I updated.
> >>
> >> There is also a pdf version of the rst file that needs to be generated.
> >
> > A PDF version will come automatically from the Quickbook version -
> > provided any additional info in the .rst is converted to doxygen-syntax comments.
> >
> > This is safe provided we assume that any inadvertent mistakes in this
> > process will be caught by running the test suite. (If they are not,
> > there is something wrong with the tests!)
> 
> You mean there should be tests for the documentation?

No - I only mean the normal tests in /test folder.

Any edits to the include files carry a risk of 'collateral damage' from mistakes.

It should not happen - but could. 

I am saying that repeating the normal tests should give sufficient assurance that this hasn't
happened.

And asking for confirmation that this is accepted by others.

Paul

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