[iterator] What documentation is actual?
Hi, While moving next_prior.hpp to Boost.Iterator I've noticed that thete are basically two versions of the documentation in Boost.Iterator: rst and QuickBook. It seems like QuickBook is in progress of being written and is largely a conversion of rst, but is incomplete in some places. I'd like to ask what's the plan about it? Since I don't know rst I converted the original documentation of next_prior.hpp to QuickBook and added it to the current QuickBook docs. I also converted advance() and distance() docs to QuickBook and fixed a few problems in the docs so that it is at least browsable and readable. If we have no plans to switch to QuickBook then I suppose it is better to remove them to avoid confusion. Also, someone has to convert next_prior.hpp docs to rst (I don't know how to do this).
Andrey Semashev wrote:
While moving next_prior.hpp to Boost.Iterator I've noticed that thete are basically two versions of the documentation in Boost.Iterator: rst and QuickBook. It seems like QuickBook is in progress of being written and is largely a conversion of rst, but is incomplete in some places.
+1 to move to Quickbook. Also, thanks for porting and fixing some rst docs to Quickbook! Regards, Michel
On 8/26/2017 1:52 PM, Andrey Semashev via Boost wrote:
Hi,
While moving next_prior.hpp to Boost.Iterator I've noticed that thete are basically two versions of the documentation in Boost.Iterator: rst and QuickBook. It seems like QuickBook is in progress of being written and is largely a conversion of rst, but is incomplete in some places.
I'd like to ask what's the plan about it?
The rst doc is being distributed. I have no idea when the quickbook version was begun and why it did not replace the rst doc. I am not even sure how the rst doc gets regenerated.
Since I don't know rst I converted the original documentation of next_prior.hpp to QuickBook and added it to the current QuickBook docs. I also converted advance() and distance() docs to QuickBook and fixed a few problems in the docs so that it is at least browsable and readable.
If we have no plans to switch to QuickBook then I suppose it is better to remove them to avoid confusion. Also, someone has to convert next_prior.hpp docs to rst (I don't know how to do this).
On 08/26/17 22:12, Edward Diener via Boost wrote:
On 8/26/2017 1:52 PM, Andrey Semashev via Boost wrote:
Hi,
While moving next_prior.hpp to Boost.Iterator I've noticed that thete are basically two versions of the documentation in Boost.Iterator: rst and QuickBook. It seems like QuickBook is in progress of being written and is largely a conversion of rst, but is incomplete in some places.
I'd like to ask what's the plan about it?
The rst doc is being distributed. I have no idea when the quickbook version was begun and why it did not replace the rst doc. I am not even sure how the rst doc gets regenerated.
I don't think it does. The Jamfile builds QuickBook, but iterator/index.html redirects to iterator/doc/index.html (not iterator/doc/html/index.html) which is committed in git along with other htmls generated from rst. So essentially QuickBook gets built but not used.
On 8/26/2017 3:40 PM, Andrey Semashev via Boost wrote:
On 08/26/17 22:12, Edward Diener via Boost wrote:
On 8/26/2017 1:52 PM, Andrey Semashev via Boost wrote:
Hi,
While moving next_prior.hpp to Boost.Iterator I've noticed that thete are basically two versions of the documentation in Boost.Iterator: rst and QuickBook. It seems like QuickBook is in progress of being written and is largely a conversion of rst, but is incomplete in some places.
I'd like to ask what's the plan about it?
The rst doc is being distributed. I have no idea when the quickbook version was begun and why it did not replace the rst doc. I am not even sure how the rst doc gets regenerated.
I don't think it does. The Jamfile builds QuickBook, but iterator/index.html redirects to iterator/doc/index.html (not iterator/doc/html/index.html) which is committed in git along with other htmls generated from rst. So essentially QuickBook gets built but not used.
I meant that I do not know how the rst files are transformed to the html and pdf files. It looks like it is done through generate.py and a GNUmakefile but the GNUmakefile tells us that the correct makefile is at http://www.boost-consulting.com/writing/GNUmakefile, which no longer exists. So it really is that we can no longer regenerate the distributed documentation for iterator from the rst files.
I think the conversion can be done using standard tools like rst2html or Sphinx. Edward Diener wrote:
It looks like it is done through generate.py and a GNUmakefile but the GNUmakefile tells us that the correct makefile is at http://www.boost-consulting.com/writing/GNUmakefile, which no longer exists.
That file can be resurrected by looking at the **history** of iterator/doc/GNUmakefile. Regards, Michel
On 8/26/2017 10:11 PM, Michel Morin via Boost wrote:
I think the conversion can be done using standard tools like rst2html or Sphinx.
Edward Diener wrote:
It looks like it is done through generate.py and a GNUmakefile but the GNUmakefile tells us that the correct makefile is at http://www.boost-consulting.com/writing/GNUmakefile, which no longer exists.
That file can be resurrected by looking at the **history** of iterator/doc/GNUmakefile.
You are right. Still the entire process is very GNU and Linux oriented. Maybe it can be done under cygwin or mingw(-64), but most probably needs a Linux OS.
Regards, Michel
Edward Diener wrote:
Still the entire process is very GNU and Linux oriented. Maybe it can be done under cygwin or mingw(-64), but most probably needs a Linux OS.
I think continuing to use rst docs makes an unnecessary burden to maintainers. Migration into quickbook docs might result in different look and feel in the generated HTMLs, but making the docs maintainable is much more important. Regards, Michel
On 8/27/2017 7:42 AM, Michel Morin via Boost wrote:
Edward Diener wrote:
Still the entire process is very GNU and Linux oriented. Maybe it can be done under cygwin or mingw(-64), but most probably needs a Linux OS.
I think continuing to use rst docs makes an unnecessary burden to maintainers. Migration into quickbook docs might result in different look and feel in the generated HTMLs, but making the docs maintainable is much more important.
I agree with you but I am personally not all that keen on going through the qbk docs and current rst docs, and updating the qbk docs to match the rst docs as far as the content is concerned. If you or anybody else would like to do it with a PR I would be happy to switch to the qbk docs as the official documentation and get rid of the rst docs and its generation system.
Regards, Michel
participants (3)
-
Andrey Semashev -
Edward Diener -
Michel Morin