[Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)
Hello, I would like to know if boost-build supports writing tutorials using Doxygen rather that using HTML or its own "quickbook" tool. At this point I have Boost.Locale documentation written with Markdown and I want to transfer it to other tool. I want to use Doxygen for it as Boost.Locale reference is already documented using Doxygen so converting the tutorials from markdown to Doxygen format seems to me much better idea then using "internal" boost documentation format. Rationale: - Doxygen is more widely available tool then quickbook. - It is independent from boost itself. - It is useful for non-boost project - Documentation generation is much simpler (requires running Doxygen) rather then using complicated tool-chain of boost-build. Thanks, Artyom
On 13/12/2010 09:25, Artyom wrote:
Hello,
I would like to know if boost-build supports writing tutorials using Doxygen rather that using HTML or its own "quickbook" tool.
Both quickbook and doxygen can be transformed to boostbook, and several boostbook documents can be linked together. Note this has little to do with boost build. The documentation system and the build system are separate things.
At this point I have Boost.Locale documentation written with Markdown and I want to transfer it to other tool. I want to use Doxygen for it as Boost.Locale reference is already documented using Doxygen so converting the tutorials from markdown to Doxygen format seems to me much better idea then using "internal" boost documentation format.
Rationale:
- Doxygen is more widely available tool then quickbook. - It is independent from boost itself. - It is useful for non-boost project - Documentation generation is much simpler (requires running Doxygen) rather then using complicated tool-chain of boost-build.
Most boost libraries already use doxygen for their "reference" part, while they use quickbook for the parts which are mostly text.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Sent: Monday, December 13, 2010 8:25 AM To: boost@lists.boost.org Subject: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)
Hello,
I would like to know if boost-build supports writing tutorials using Doxygen rather that using HTML or its own "quickbook" tool.
At this point I have Boost.Locale documentation written with Markdown and I want to transfer it to other tool. I want to use Doxygen for it as Boost.Locale reference is already documented using Doxygen so converting the tutorials from markdown to Doxygen format seems to me much better idea then using "internal" boost documentation format.
Rationale:
- Doxygen is more widely available tool then quickbook. - It is independent from boost itself. - It is useful for non-boost project - Documentation generation is much simpler (requires running Doxygen) rather then using complicated tool-chain of boost-build.
Downside :-(( the results are not as nice ;-) (and it will be as easy to convert Markdown to Quickbook as to convert to Doxygen. There is a html to Quickbook conversion tool somewhere too). You can't easily embed code snippets into the Quickbook text, ensuring that the code example and the docs don't get separated, and provide helpful comment when you are reading the full example C++. And are not available in pdf. (Very valuable in that one can search the whole documentation for words, providing a substitute for a proper index (something we still haven't cracked). I would still wrap it in Quickbook but you can also provide Doxygen format as reference AND for tutorial. (Perhaps some expert can suggest how to get the reference and tutorial separated ?) The 'toolchain' in a real pain to get going, but your readers will thank you for your perseverance! Once set up it runs painlessly to update, and can be done by anyone with a text editor Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
Downside :-(( the results are not as nice ;-)
The results is the content not the "nice representation" and to be honest, Doxygen reference documentation is a way better then the "reference" I usually see in boost libraries.
(and it will be as easy to convert Markdown to Quickbook as to convert to Doxygen. There is a html to Quickbook conversion tool somewhere too).
I just prefer to have one tool I can build documentation with and I want to have a one syntax to work with. Doxygen does the job well.
I would still wrap it in Quickbook but you can also provide Doxygen format as reference AND for tutorial. (Perhaps some expert can suggest how to get the reference and tutorial separated ?)
Ok this is good because this makes the life much easier to me not requiring to use quickbook and allowing to "debug" my documentation in fast and easy way.
The 'toolchain' in a real pain to get going [...] Once set up it runs painlessly to update, and can be done by anyone with a text editor
As it can be updated with Doxygen written documentation and tutorials as well. Thanks, Artyom
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Sent: Monday, December 13, 2010 1:22 PM To: boost@lists.boost.org Subject: Re: [boost] [Documentation] Does Boost-Build support Doxygen documentation for tutorials (rather then quickbook)
Downside :-(( the results are not as nice ;-)
The results is the content not the "nice representation" and to be honest, Doxygen reference documentation is a way better then the "reference" I usually see in boost libraries.
I'm curious in what way you think it is superior. And of course, you can *also* view it in Doxygen format, if you prefer, provided the Doxygen files are provided in the download. I've been arguing for some time that this should always be provided. I also feel that much of the benefit from Doxygen comes from the 'in-code' documentation of each function. This also feeds through into the Quickbook reference section. But it needs Doxygen documenting while writing the C++ code, as you go along. I found that adding it later was very tedious (and I'd forgotten what some things were meant to do! ;-) If I were starting a new project, I would definitely do this - then I might be able to understand my own code a year or so later ;-) I have found it best to run Doxygen (which is quick and gives better error messages for Doxygen comments mistakes) to check before running the full Quickbook html and pdf output. Build time is significant if you have a good sized package (Boost.Math and SVG Plot are both over 500 pages in pdf) - though it has improved markedly with Steven Watanbe's recent good work - for which many thanks (and with a little help from some faster hardware ;-) I still urge you to get the whole Quickbook thing to work - however painful it may seem. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 13 December 2010 08:25, Artyom <artyomtnk@yahoo.com> wrote:
I would like to know if boost-build supports writing tutorials using Doxygen rather that using HTML or its own "quickbook" tool.
We do use straight doxygen documentation in at least on place: http://www.boost.org/doc/libs/1_45_0/libs/gil/doc/index.html To create boost documentation, you don't have to use boost build, but you do have to make it reasonably easy for others to generate the documentation. In GIL's case, it uses shell scripts, which isn't ideal for windows users. Also, be aware that doxygen can generate long file names which don't meet our requirements. GIL uses a script to rename them (although there are some broken links, I haven't looked into why that is, I don't really know doxygen). I think boost build's doxygen support is tailored for boostbook, but it would be nice to be able to use it for other purposes. I'm not sure what that would be involved, you might want to ask on the build list. Daniel
AMDG On 12/13/2010 7:26 AM, Daniel James wrote:
We do use straight doxygen documentation in at least on place:
http://www.boost.org/doc/libs/1_45_0/libs/gil/doc/index.html
To create boost documentation, you don't have to use boost build, but you do have to make it reasonably easy for others to generate the documentation. In GIL's case, it uses shell scripts, which isn't ideal for windows users. Also, be aware that doxygen can generate long file names which don't meet our requirements. GIL uses a script to rename them (although there are some broken links, I haven't looked into why that is, I don't really know doxygen).
I think boost build's doxygen support is tailored for boostbook, but it would be nice to be able to use it for other purposes. I'm not sure what that would be involved, you might want to ask on the build list.
Boost.Build will generate html from doxygen if the target name ends with ".html". In Christ, Steven Watanabe
On 13 December 2010 08:25, Artyom <artyomtnk@yahoo.com> wrote:
I would like to know if boost-build supports writing tutorials using Doxygen rather that using HTML or its own "quickbook" tool.
We do use straight doxygen documentation in at least on place:
http://www.boost.org/doc/libs/1_45_0/libs/gil/doc/index.html
To create boost documentation, you don't have to use boost build, but you do have to make it reasonably easy for others to generate the documentation.
Thanks this answers my question completely. Artyom
participants (5)
-
Artyom -
Daniel James -
Mathias Gaunard -
Paul A. Bristow -
Steven Watanabe