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

Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2015-08-24 14:53:19

On 8/24/2015 2:35 PM, Steven Watanabe wrote:
> AMDG
>
> On 08/24/2015 12:06 PM, 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.
>>
>> I tried 'python generate.py' on Windows but this led to the error:
>>
>>> make ...
>>> make: Nothing to be done for `counting_iterator.html'.
>
>    It sounds like the timestamps on the
> generated files are not older than
> the sources.  Try touching the sources
> or deleting the html.

The problem is that the actual makefile is something that was on the 
Boost consulting site, since its licensed was GPLed. The makefile that 
gets generated by the python code, called GNUmakefile, says:

> 	@${ECHO} "<boost-root>/libs/iterator/doc/GNUmakefile should be replaced by"
> 	@${ECHO}
> 	@${ECHO} "    http://www.boost-consulting.com/writing/GNUmakefile,"
> 	@${ECHO}
> 	@${ECHO} "before proceeding.  That file is not included in the Boost"
> 	@${ECHO} "distribution because it is licensed under the GPL, which violates"
> 	@${ECHO} "Boost license requirements."

I have e-mailed Dave Abrahams to see if the GNUmakefile is still around 
anywhere, since I did not find it on the Internet archive 
waybackmachine. If it is not around there is a set of quickbook files 
that can be used to generate the doc, but the output of that generation 
looks slightly different in design from what we currently show when we 
distribute Boost.

I think Thomas Witt originally created the quickbook version about a 
decade ago and I assume both the rst version and the quickbook version 
have been kept in sync if any documentation changes have been made to 
iterator.