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

Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-08-26 07:06:32

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? 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.