Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-08-26 07:41:31
On 26.08.2015 14:17, Paul A. Bristow wrote:
>> -----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
> 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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk