[doxygen] CSS/Temple files for Doxygen
Hello, Where can I find CSS files/Template files suitable for Doxygen documentation generation? So I can make Doxygen output to have more Boost-like style. Artyom Beilis -------------- CppCMS - C++ Web Framework: http://cppcms.sf.net/ CppDB - C++ SQL Connectivity: http://cppcms.sf.net/sql/cppdb/
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis Sent: Wednesday, June 22, 2011 4:10 PM To: boost@lists.boost.org Subject: [boost] [doxygen] CSS/Temple files for Doxygen
Where can I find CSS files/Template files suitable for Doxygen documentation generation?
So I can make Doxygen output to have more Boost-like style.
I'm not sure you really can :-( When I build Doxygen standalone, I use the default Doxygen .css, but I only do this to make sure that all the Doxygen //! comments in my code are correct. This is because it is much quick to run the Doxywizard, than the full Quickbook toolchain. And also so that you can tell Doxygen to warn you about the classes, functions etc that you have failed to document, so far. Thus armed with 'correct' .*pp, I add the Doxygen Reference section to the real docs written in Quickbook, so the final docs have a consistent Boost look'n'feel. You may find helpful a skeleton docs example at: boost-sandbox/guild/mylibrary/libs/doc You should be able to re-build these docs in html and pdf. (If you can, you can be confident that you have your user-config.jam settings and all the .exe files in the right places). You may also find helpful some jottings on what I did wrong en route to producing a few library docs at \boost-sandbox\tools\quick_auto_dox_index\libs\quick_auto_dox_index\doc You should be able to build these docs too. This will produce your docs in the best Boost Style ;-) Good luck. Paul
From: Paul A. Bristow <pbristow@hetp.u-net.com>
From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis Sent: Wednesday, June 22, 2011 4:10 PM To: boost@lists.boost.org Subject: [boost] [doxygen] CSS/Temple files for Doxygen
Where can I find CSS files/Template files suitable for Doxygen documentation generation?
So I can make Doxygen output to have more Boost-like style.
I'm not sure you really can :-(
[snip]
Thus armed with 'correct' .*pp, I add the Doxygen Reference section to the real docs written in Quickbook, so the final docs have a consistent Boost look'n'feel.
[snip]
Paul
I'm not sure that full docbook toolchain is good for me as all tutorials are the documentation of Boost.Locale is written using Doxygen and I'm not using quickbook at all. Does it capable at all to generate a nice index and hierarchical pages from Doxygen. I mean I want to Boostify this: http://cppcms.sourceforge.net/boost_locale/html/index.html So it seems to me that I'll need to hack Doxygen styles a little to make them more "Boosty" Artyom Beilis -------------- CppCMS - C++ Web Framework: http://cppcms.sf.net/ CppDB - C++ SQL Connectivity: http://cppcms.sf.net/sql/cppdb/
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis Sent: Wednesday, June 22, 2011 7:28 PM To: boost@lists.boost.org Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
So I can make Doxygen output to have more Boost-like style.
I'm not sure you really can :-(
[snip]
Thus armed with 'correct' .*pp, I add the Doxygen Reference section to the real docs written in Quickbook, so the final docs have a consistent Boost look'n'feel.
[snip]
Paul
I'm not sure that full docbook toolchain is good for me as all tutorials are the documentation of Boost.Locale is written using Doxygen and I'm not using quickbook at all.
Does it capable at all to generate a nice index and hierarchical pages from Doxygen.
I mean I want to Boostify this:
http://cppcms.sourceforge.net/boost_locale/html/index.html
So it seems to me that I'll need to hack Doxygen styles a little to make them more "Boosty"
I know you don't want to hear this, but IMO re-factoring your (very nice) docs into Quickbook is the only way to get it more Boosty (but with the Doxygen reference section - and an index). If you can point me to the file with the \mainpage, I am willing to sketch out a bit to show how you would need to convert it to Quickbook. It'll be some nasty cut'n'pasting and global edit changes, but it will end up looking much the same in the html (and pdf - a big plus of the toolchain). Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 7/8/2011 10:29 AM, Paul A. Bristow wrote:
[mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis I mean I want to Boostify this:
http://cppcms.sourceforge.net/boost_locale/html/index.html
So it seems to me that I'll need to hack Doxygen styles a little to make them more "Boosty"
I know you don't want to hear this, but IMO re-factoring your (very nice) docs into Quickbook is the only way to get it more Boosty (but with the Doxygen reference section - and an index).
I highly recommend moving to the regular Boost documentation toolchain. Not only do you get the look & feel. But you also get the benefit of inclusion with the rest of the libraries that produce BoostBook documentation. Hence increasing the exposure of your library to users. When the SF file download stats come back, you might want to look at the count for the PDF docs to give you and idea of the added exposure. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org (msn) - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
Am Freitag, den 08.07.2011, 13:18 +0200 schrieb Rene Rivera <grafikrobot@gmail.com>:
On 7/8/2011 10:29 AM, Paul A. Bristow wrote:
[mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis I mean I want to Boostify this:
http://cppcms.sourceforge.net/boost_locale/html/index.html
So it seems to me that I'll need to hack Doxygen styles a little to make them more "Boosty"
I know you don't want to hear this, but IMO re-factoring your (very nice) docs into Quickbook is the only way to get it more Boosty (but with the Doxygen reference section - and an index).
I highly recommend moving to the regular Boost documentation toolchain. Not only do you get the look & feel. But you also get the benefit of inclusion with the rest of the libraries that produce BoostBook documentation. Hence increasing the exposure of your library to users. When the SF file download stats come back, you might want to look at the count for the PDF docs to give you and idea of the added exposure.
Actually neither Quickbook nor BoostBook is strictly required for a consistent look and feel of the generated HTML and PDF files. The common base is DocBook. Therefore, Boosty documentation may be generated from any markup language that can somehow be transformed into DocBook. This includes AsciiDoc, BoostBook, markdown, reStructuredText, textile, HTML, LaTeX, Quickbook, and maybe more. Doxygen is not (fully*) supported, unfortunately. Instead of hacking the Doxygen CSS files, you might also hack some XSL files that allow Doxygen XML output to be transformed into DocBook. This would be a huge benefit for other projects too. cheers, Daniel * There is an XSL stylesheet in BoostBook that transforms the reference part of Doxygen XML output to BoostBook, it strips the tutorial etc.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel Pfeifer Sent: Saturday, July 09, 2011 9:03 AM To: boost@lists.boost.org Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
Am Freitag, den 08.07.2011, 13:18 +0200 schrieb Rene Rivera <grafikrobot@gmail.com>:
On 7/8/2011 10:29 AM, Paul A. Bristow wrote:
[mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis I mean I want to Boostify this:
http://cppcms.sourceforge.net/boost_locale/html/index.html
So it seems to me that I'll need to hack Doxygen styles a little to make them more "Boosty"
I know you don't want to hear this, but IMO re-factoring your (very nice) docs into Quickbook is the only way to get it more Boosty (but with the Doxygen reference section - and an index).
I highly recommend moving to the regular Boost documentation toolchain. Not only do you get the look & feel. But you also get the benefit of inclusion with the rest of the libraries that produce BoostBook documentation. Hence increasing the exposure of your library to users. When the SF file download stats come back, you might want to look at the count for the PDF docs to give you and idea of the added exposure.
Actually neither Quickbook nor BoostBook is strictly required for a consistent look and feel of
the
generated HTML and PDF files.
The common base is DocBook. Therefore, Boosty documentation may be generated from any markup language that can somehow be transformed into DocBook. This includes AsciiDoc, BoostBook, markdown, reStructuredText, textile, HTML, LaTeX, Quickbook, and maybe more. Doxygen is not (fully*) supported, unfortunately.
Instead of hacking the Doxygen CSS files, you might also hack some XSL files that allow Doxygen XML output to be transformed into DocBook. This would be a huge benefit for other projects too.
What you say is entirely correct, but ignores the maintainability benefits if everyone generates their docs in the same way using Quickbook (with Doxygen reference section). We need to consider what happens when the original author stops maintaining, the fate of nearly all older Boost libraries. Quickbook is such an easy and yet powerful tool to use and works with any text editor (though coloring is nice). OK, setting up the toolchain is a PITA (but I fear so is any toolchain), but once one is over that hurdle, writing the docs is a doddle. Even a re-write of the Pool docs from html didn't take that long (and revealed some deficiencies in the original). 'Automatic' conversion didn't really help much more than lots of cut'n'paste. (It revealed that you need to know what the software does - and in places I didn't!) Paul PS Long term, a tool that *really* understands C++ like the Clang compiler should be able to generate a better reference section than Doxygen which does impressively well considering but can get confused). --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
----- Original Message ----
From: Paul A. Bristow <pbristow@hetp.u-net.com>
Quickbook is such an easy and yet powerful tool to use and works with any text editor (though coloring is nice).
OK, setting up the toolchain is a PITA (but I fear so is any toolchain), but once one is over that hurdle, writing the docs is a doddle.
Even a re-write of the Pool docs from html didn't take that long (and revealed some deficiencies in the original). 'Automatic' conversion didn't really help much more than lots of cut'n'paste. (It revealed that you need to know what the software does - and in places I didn't!)
Paul
PS Long term, a tool that *really* understands C++ like the Clang compiler should be able to generate a better reference section than Doxygen which does impressively well considering but can get confused).
To be honest... I prefer to use ONE too for projects I work on. With Doxygen I can generate both great tutorials and reference (in-source-code) documentation, easily integrate them and what is most important to use ONE - SAME syntax. The only project using quickbook today is Boost. And it can't be really used outside the scope of Boost.Build. I don't develop for Boost only but rather have several different FOSS projects that use Doxygen and none of them use Boost.Build. So instead of learning one more tool, create an entire toolchain of Doxyen/Quickbook/DocBook/HTML I prefer to use one tool that can be easily integrated with CMake and easy to install. To be honest. I find Doxygen a very good tool for documenting software and I don't understand why Boost hadn't adopted one... But this is other story. Finally I don't want to move to other tool especially when Boost does not enforce me. I'll keep Doxygen as-is and maybe tweak CSS a little BTW Doxygen knows to produce PDFs as well. Thanks, Artyom Beilis -------------- CppCMS - C++ Web Framework: http://cppcms.sf.net/ CppDB - C++ SQL Connectivity: http://cppcms.sf.net/sql/cppdb/
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Beilis Sent: Saturday, July 09, 2011 8:50 PM To: boost@lists.boost.org Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
----- Original Message ----
From: Paul A. Bristow <pbristow@hetp.u-net.com> <snip>
To be honest...
I prefer to use ONE too for projects I work on.
With Doxygen I can generate both great tutorials and reference (in-source-code) documentation, easily integrate them and what is most important to use ONE - SAME syntax.
The only project using quickbook today is Boost. And it can't be really used outside the scope of Boost.Build.
I don't develop for Boost only but rather have several different FOSS projects that use Doxygen and none of them use Boost.Build.
So instead of learning one more tool, create an entire toolchain of Doxyen/Quickbook/DocBook/HTML I prefer to use one tool that can be easily integrated with CMake and easy to install.
To be honest. I find Doxygen a very good tool for documenting software and I don't understand why Boost hadn't adopted one... But this is other story.
Finally I don't want to move to other tool especially when Boost does not enforce me. I'll keep Doxygen as-is and maybe tweak CSS a little
OK, I can see I'm not going to persuade you :-) But your Doxygen docs looks nice and are up to Boost standards. (Have you thought of adding custom Doxygen html header/footers to make it look Boostier?) Paul PS
BTW Doxygen knows to produce PDFs as well.
"PDF can be generated from the LaTeX output" Have you done this for your docs? Boost PDF versions are popular.
From: Paul A. Bristow <pbristow@hetp.u-net.com>
But your Doxygen docs looks nice and are up to Boost standards.
(Have you thought of adding custom Doxygen html header/footers to make it look Boostier?)
Actually I already did, just hadn't published it yet, it will have Boost header and a nice navigation plane on a side.
BTW Doxygen knows to produce PDFs as well.
"PDF can be generated from the LaTeX output"
Have you done this for your docs? Boost PDF versions are popular.
Currently it does not, as LaTeX straggles with Unicode diversity. Boost.Locale docs use samples from: Japanese, Chinese, Hebrew, Arabic, French, Greek, German, Russian and probably some other languages I had forgotten. I need to tweak it, so it would use xelatex that has much better Unicode support. But this is something really Boost.Locale specific, it does not have such problems for other libraries. Artyom Beilis -------------- CppCMS - C++ Web Framework: http://cppcms.sf.net/ CppDB - C++ SQL Connectivity: http://cppcms.sf.net/sql/cppdb/
On 9 July 2011 09:02, Daniel Pfeifer <daniel@pfeifer-mail.de> wrote:
The common base is DocBook. Therefore, Boosty documentation may be generated from any markup language that can somehow be transformed into DocBook. This includes AsciiDoc, BoostBook, markdown, reStructuredText, textile, HTML, LaTeX, Quickbook, and maybe more. Doxygen is not (fully*) supported, unfortunately.
The weak point in our documentation toolchain is using docbook on windows. That's where we have most issues. So I don't think it'd be a good idea to use it when using a tool that can already generate html and pdf.
Instead of hacking the Doxygen CSS files, you might also hack some XSL files that allow Doxygen XML output to be transformed into DocBook. This would be a huge benefit for other projects too.
The doxygen xml to quickbook converter used for the geometry documentation is pretty much doing that (via. quickbook). Adapting it to generate docbook directly might be an easier solution than using XSL.
Hello,
Where can I find CSS files/Template files suitable for Doxygen documentation generation?
So I can make Doxygen output to have more Boost-like style.
You can make Doxygen output XML and transform that to BoostBook -> DocBook -> HTML. This is how many Boost libraries generate the reference section in their documentation. cheers, Daniel
----- Original Message ----
From: Daniel Pfeifer <daniel@pfeifer-mail.de> To: boost@lists.boost.org Sent: Wed, June 22, 2011 6:40:11 PM Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
Hello,
Where can I find CSS files/Template files suitable for Doxygen documentation generation?
So I can make Doxygen output to have more Boost-like style.
You can make Doxygen output XML and transform that to BoostBook -> DocBook -> HTML. This is how many Boost libraries generate the reference section in their documentation.
cheers, Daniel
The point is that I need entire documentation not a reference only. Artyom Beilis -------------- CppCMS - C++ Web Framework: http://cppcms.sf.net/ CppDB - C++ SQL Connectivity: http://cppcms.sf.net/sql/cppdb/
AMDG On 06/22/2011 08:09 AM, Artyom Beilis wrote:
Hello,
Where can I find CSS files/Template files suitable for Doxygen documentation generation?
So I can make Doxygen output to have more Boost-like style.
I don't think anyone's tried this before. I suppose you could start with doc/src/boostbook.css. It would definitely need some adjustments to work with doxygen's output. Really, though, doxygen's default stylesheet looks fine and it's not like all the Boost documentation has a consistent look and feel to begin with. In Christ, Steven Watanabe
participants (6)
-
Artyom Beilis -
Daniel James -
Daniel Pfeifer -
Paul A. Bristow -
Rene Rivera -
Steven Watanabe