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? I haven't seen those yet. If you want examples in the docs to be actual and at least compilable, the best way to do this that I know is to make them separate .cpp files and import into QuickBook document. Then you can add them to the test suite (probably as compile targets rather than run).

I am willing to do this if people think it worthwhile.

I think any work towards a single version of the docs is worthwhile. Ideally, we should not lose information in the process, so whatever is missing in QuickBook/Doxygen comments should be moved there. I appreciate this is a time consuming task, so I'm grateful to anyone who takes it.