Hello, I'm developing a project for boost (discussion can be found here: http://lists.boost.org/Archives/boost/2013/01/200598.php) I was wondering how one writes documentation. I did find some templates here, but they seem outdated (ot at least different), compared to the documentation files that already exist for the libraries. So, are there any new templates? Is there a html generation tool I should use? -- Borislav
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
Hello,
I'm developing a project for boost (discussion can be found here: http://lists.boost.org/Archives/boost/2013/01/200598.php)
I was wondering how one writes documentation. I did find some templates here, but they seem outdated (ot at least different), compared to the documentation files that already exist for the libraries.
So, are there any new templates? Is there a html generation tool I should use?
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site: http://www.boost.org/doc/libs/release/doc/html/quickbook.html The docs are written in QuickBook themselves so that's what your docs will look like in the end. On the front page you will find a link to quickbook.qbk which you can use as a starting point. There are no requirements on the documentation structure, AFAIK. But generally it is a good idea to provide a tutorial, some expanded description and formal reference sections. Of course, it all depends on how large and complex the library is; sometimes it is enough to just have a tutorial if the library is small.
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
Hello,
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
The docs are written in QuickBook themselves so that's what your docs will look like in the end. On the front page you will find a link to quickbook.qbk which you can use as a starting point.
There are no requirements on the documentation structure, AFAIK. But generally it is a good idea to provide a tutorial, some expanded description and formal reference sections. Of course, it all depends on how large and complex the library is; sometimes it is enough to just have a tutorial if the library is small.
Many thanks :) This seems like a great tool
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
Hi again, Perhaps you could help me a bit more? I tried creating a Jamfile.v2 for my book. Here it is: using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ; It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output: warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets... Am I missing something? -- Borislav
On Saturday 02 February 2013 18:08:19 Borislav Stanimirov wrote:
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
Hi again,
Perhaps you could help me a bit more?
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output:
warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets...
Am I missing something?
I'm not sure. Did you also install xsltproc and docbook packages as described in the installation guide?
On 02/02/2013 06:33 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 18:08:19 Borislav Stanimirov wrote:
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
Hi again,
Perhaps you could help me a bit more?
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output:
warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets...
Am I missing something?
I'm not sure. Did you also install xsltproc and docbook packages as described in the installation guide?
Yes I did. $ dpkg --get-selections | grep -e docbook -e xsltproc docbook install docbook-xml install docbook-xsl install xsltproc install I don't have doxygen though. Could that be the problem? - Borislav
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Borislav Stanimirov Sent: Saturday, February 02, 2013 4:44 PM To: boost@lists.boost.org Subject: Re: [boost] Writing documentation
On 02/02/2013 06:33 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 18:08:19 Borislav Stanimirov wrote:
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
Hi again,
Perhaps you could help me a bit more?
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output:
warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets...
Am I missing something?
I'm not sure. Did you also install xsltproc and docbook packages as described in the installation guide?
Yes I did.
$ dpkg --get-selections | grep -e docbook -e xsltproc docbook install docbook-xml install docbook-xsl install xsltproc install
I don't have doxygen though. Could that be the problem?
You don't need Doxygen unless you use it. I think not all the versions of Docbook stuff work - strongly recommend using exactly these two versions. The standard nix install might not give these? My user_config.jam has using boostbook : "C:\\Program Files\\docbook\\docbook-xsl-1.77.1" # OK 23 Aug12 # Contains eXtended Style Sheet programs. : "C:\\Program Files\\DocbookXML\\42" # dir exists and contains docbookx.dtd 4.2 # actually C:\Program Files\DocbookXML\42 ; (You should get a line generating file standalone_HTML_manifest) HTH Paul PS Don't give up! Once the pig is setup, Quickbook works fine ;-) --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On Saturday 02 February 2013 18:43:42 Borislav Stanimirov wrote:
On 02/02/2013 06:33 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 18:08:19 Borislav Stanimirov wrote:
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries. You can find its docs on the site:
http://www.boost.org/doc/libs/release/doc/html/quickbook.html
Hi again,
Perhaps you could help me a bit more?
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output:
warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets...
Am I missing something?
I'm not sure. Did you also install xsltproc and docbook packages as described in the installation guide?
Yes I did.
$ dpkg --get-selections | grep -e docbook -e xsltproc docbook install docbook-xml install docbook-xsl install xsltproc install
I don't have doxygen though. Could that be the problem?
This shouldn't be a problem as long as you don't use it. Are you sure you also added the necessary lines to user-config.jam? Here's what I have in mine: using xsltproc ; using boostbook ; using doxygen ; using quickbook ; I have the standard docbook packages from Kubuntu 12.10. I just created the Jamfile.v2 you posted in libs/mixin/doc and a dummy qbk based on quickbook.qbk (with the QuickBook header and a single empty section). Then I ran "bjam release link=static libs/mixin/doc" from Boost root and got the html directory there afterwards. Not sure what could go wrong.
Perhaps you could help me a bit more?
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ; xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
It successfully generateates mixin_doc.xml but doesn't generate any html. Here's the output:
warn: Unable to construct ./mixin ...found 7 targets... ...updating 4 targets... common.mkdir bin common.mkdir bin/gcc-4.6 common.mkdir bin/gcc-4.6/debug quickbook.quickbook-to-boostbook bin/gcc-4.6/debug/mixin_doc.xml Generating Output File: bin/gcc-4.6/debug/mixin_doc.xml ...updated 4 targets...
Am I missing something?
I suspect user-config.jam doesn't have what it needs to find Docbook etc? In case you haven't seen it already, this page: https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted should have the full lowdown on what you need. John.
On 02/02/2013 07:18 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 18:43:42 Borislav Stanimirov wrote:
On 02/02/2013 06:33 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 18:08:19 Borislav Stanimirov wrote:
On 02/02/2013 12:00 PM, Andrey Semashev wrote:
On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
I was wondering how one writes documentation.
I found QuickBook to be the easiest tool for documenting Boost libraries.
It successfully generateates mixin_doc.xml but doesn't generate any html.
Are you sure you also added the necessary lines to user-config.jam? Here's what I have in mine:
using xsltproc ; using boostbook ; using doxygen ; using quickbook ;
Thanks, again! That was it. I had forgotten to add using xsltproc. -- Borislav
On 2 February 2013 16:08, Borislav Stanimirov <b.stanimirov@abv.bg> wrote:
I tried creating a Jamfile.v2 for my book. Here it is:
using quickbook ;
Also add 'using boostbook ;'
xml mixin_doc : mixin.qbk ; boostbook mixin : mixin_doc ; install html ;
You can also add to it your user-config.jam, but it's better to add it to the jamfile so that it will work for other people who don't have it in their user-config.jam.
participants (5)
-
Andrey Semashev -
Borislav Stanimirov -
Daniel James -
John Maddock -
Paul A. Bristow