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

On 26.08.2015 14:17, Paul A. Bristow wrote:

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 26 August 2015 12:07 To: boost@lists.boost.org 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@lists.boost.org] On Behalf Of Edward Diener Sent: 25 August 2015 18:01 To: boost@lists.boost.org 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 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.

I think adding Doxygen comments without changing the actual code is a pretty safe operation. Running tests afterwards would be a sufficient confirmation for me.