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.

On 8/25/2015 4:42 AM, Paul A. Bristow wrote:

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 24 August 2015 19:53 To: boost@lists.boost.org Subject: Re: [boost] [iterator] Regenerating the iterator docs

...

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.

<snip>

As the Irishman said when asked the way "I wouldn't start from here!"

<g>

The long-term answer is to convert the information in RST format to Doxygen-syntax comments in the actual code.

Then everything will be generated automatically using the Quickbook toolchain, including an index.

We do have quickbook files for the documentation, which appears a duplicate of the RST docs in content. The jamfile for building the quickbook docs is a little sparse ( no pdf and no index ) but I can update that. The difference is that the build from RST files, which is what the end-user currently sees in the Boost distros, has a slightly more elaborate look-and-feel than what the quickbook docs generate. I am not up to duplicating that more elaborate look-and-feel but maybe others would like to do it if they feel it is needed.

...

in the Boost distros, has a slightly more elaborate look-and-feel than what the quickbook docs generate. I am not up to duplicating that more elaborate look-and-feel but maybe others would like to do it if they feel it is needed. I may find time to look at that - but not immediately.

Is the different look and feel worth preserving if it presents a maintenance issue? Personally I'd rather see the docs up to date and the library maintained, John.

On 8/26/2015 8:15 AM, Glen Fernandes wrote:

Paul wrote:

...

The long-term answer is to convert the information in RST format to Doxygen-syntax comments in the actual code.

Do we plan to support RST based generators like Sphinx in the future? (I don't even know if Quickbook is under any active development. Is it?)

I think Quickbook is pretty good and it is a part of Boost. I also think it is under active development.

On 8/26/15 5:45 AM, Edward Diener wrote:

On 8/26/2015 8:15 AM, Glen Fernandes wrote:

...

Paul wrote:

...

The long-term answer is to convert the information in RST format to Doxygen-syntax comments in the actual code.

Do we plan to support RST based generators like Sphinx in the future? (I don't even know if Quickbook is under any active development. Is it?)

I think Quickbook is pretty good and it is a part of Boost. I also think it is under active development.

Long standing boost policy is to require HTML files. How they are generated has been according to the preference the author - or I guess the maintainer. Unless we want to change this policy - I guess there's not a lot to discuss. Robert Ramey

On 8/26/2015 11:52 AM, Glen Fernandes wrote:

Robert wrote:

...

Long standing boost policy is to require HTML files. How they are generated has been according to the preference the author - or I guess the maintainer. Unless we want to change this policy - I guess there's not a lot to discuss.

Policy is a separate matter. This is more about convenience/maintainability.

I use Quickbook now and I like that I do not have to generate the documentation myself and keep the generated .html files in my repository. All that lives in the repository is my .qbk content. Many other authors/maintainers also do this.

If Sphinx was supported similarly, and I had the choice between Quickbook and Sphinx, I'd probably move to .rst from .qbk.

If there were a Boost sphinx tool as part of Boost I don't see why those who want to use .rst instead of .qbk files should not be able to do so. But whatever is used there needs to be something in Boost so that any end-user can generate the HTML docs using the Build system.

On 8/25/2015 4:50 AM, Andrey Semashev wrote:

On Mon, Aug 24, 2015 at 9: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.

FWIW, when I updated Boost.Iterator docs in one of my PRs I only updated .qbk. I have no idea what .rst is, how to edit it or generate output from it. Also, as I remember when I did the change the .qbk docs looked more actual to me, so I figured that .rst was something outdated.

Unfortunately whatever changes you made did not appear in any Boost release for the end-users unless they manually built the documentation using quickbook. We all know what this entails in user-config.jam.

I'd prefer we only keep one copy of the docs, preferably QuickBook, and remove the other to avoid the confusion.

I am in agreement with you. But this does mean that the documentation format which we distribute as the iterator documentation does change in its overall look. The documentation which the end-user sees in the Boost 1.59 distro is the one generated by the .rst files and process, not the one generated by the quickbook files.

On 25 August 2015 at 18:01, Edward Diener wrote:

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.

The pdfs are not required and not maintained, so they should probably be deleted, and links to them removed.

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.

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.

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 26 August 2015 12:53 To: boost@lists.boost.org Subject: Re: [boost] [iterator] Regenerating the iterator docs

On 8/26/2015 6:41 AM, 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!)

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

If you are willing to do this for the latest iterator docs on 'develop', and create a PR for the changes, I will approve the PR. As usual let's do this on 'develop' and afterwards I can merge the changes to 'master'.

Since I am thwarted by what I was just going to do, I'll take this on. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830