Recomended way of generating documentation
Hi, I'm currently in the process of generating documentation in a Boost usable format and got a couple questions. The documentation is currently in-source in Doxygen format and has a markdown file for the start page. 1. Which aliases do I need and for what? I've seen boostdoc and boostrelease but couldn't find a description what and why they are 2. Where do the documentation files need to go? It seems using BJam naively outputs them to bin.v2 not to the libraries doc folder which I'd even see useful because generated files should not clobber the source tree 3. What benefit is there going from Doxygen (over multiple conversions) to boostbook? Can't I just go from Doxygen to HTML? 4. If the above: Calling `doxygen mylib.html` in BJam generates a mylib folder and a mylib.html redirecting into that folder. Both hardcoded to go into a subfolder of bin.v2. How is that useful/useable? Wouldn't I want a 'html' folder and an index.html redirecting to the index.html contained or no redirection file at all? 5. As I'm thinking about calling doxygen manually: Do I need to do anything so e.g. mylib shows up in boost/doc/html? Why is only a subset of the libraries there? Thanks for any help or pointers! Alexander Grund
On Sun, Dec 29, 2019 at 7:05 AM Alexander Grund via Boost < boost@lists.boost.org> wrote:
Hi,
I'm currently in the process of generating documentation in a Boost usable format and got a couple questions. The documentation is currently in-source in Doxygen format and has a markdown file for the start page.
1. Which aliases do I need and for what? I've seen boostdoc and boostrelease but couldn't find a description what and why they are
Those are explained in the doc building section here < https://www.boost.org/development/requirements.html#Integration> -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
On 12/29/2019 8:04 AM, Alexander Grund via Boost wrote:
Hi,
I'm currently in the process of generating documentation in a Boost usable format and got a couple questions. The documentation is currently in-source in Doxygen format and has a markdown file for the start page.
1. Which aliases do I need and for what? I've seen boostdoc and boostrelease but couldn't find a description what and why they are 2. Where do the documentation files need to go? It seems using BJam naively outputs them to bin.v2 not to the libraries doc folder which I'd even see useful because generated files should not clobber the source tree 3. What benefit is there going from Doxygen (over multiple conversions) to boostbook? Can't I just go from Doxygen to HTML? 4. If the above: Calling `doxygen mylib.html` in BJam generates a mylib folder and a mylib.html redirecting into that folder. Both hardcoded to go into a subfolder of bin.v2. How is that useful/useable? Wouldn't I want a 'html' folder and an index.html redirecting to the index.html contained or no redirection file at all? 5. As I'm thinking about calling doxygen manually: Do I need to do anything so e.g. mylib shows up in boost/doc/html? Why is only a subset of the libraries there?
Thanks for any help or pointers!
You can look at the jamfile in the doc subfolder of a library to get an idea of how to set yours up to generate documentation. A popular method to provide documentation for a library is to write it using quickbook files placed in your doc subfolder and use the jamfile in that folder to convert quickbook to html and/or pdf documentation. The quickbook files, the jamfile, and an index files are the only doc files that need be in git. I personally find quickbook immensely easier for creating documentation than boostbook or plain html.
On Sun, 29 Dec 2019, 14:04 Alexander Grund via Boost, <boost@lists.boost.org> wrote:
3. What benefit is there going from Doxygen (over multiple conversions)
to boostbook? Can't I just go from Doxygen to HTML?
So that you can cross-reference the Doxygen reference with whatever other documentation you have, which requires the whole documentation to eventually be in a single format (which is Boostbook). And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
Treading carefully here as I'm new to boost library maintenance...
So that you can cross-reference the Doxygen reference with whatever other documentation you have
http://www.doxygen.nl/manual/autolink.html suggests that links to external URLs are recognised by doxygen. Presumably linking to the correct place vis-a-vis release/developer builds can be controlled with a macro in a generated Doxyfile?
And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
Other than the very pleasing boost documentation styling, is this seemingly convoluted conversion route necessary? Is it not possible to configure a Doxyfile to contain the correct styling? I have no knowledge of the evolution of boost documentation and have no axe to grind, but as a newcomer it seems to me that there is a lot of 'unnecessary' compication in the production of documentation. I appreaciate that there's no real sense in revisting existing libraries, but for new ones wouldn't it be prudent to choose the shortest possible path which involves the least learning and maintenance? On Wed, 1 Jan 2020 at 01:28, Mathias Gaunard via Boost < boost@lists.boost.org> wrote:
On Sun, 29 Dec 2019, 14:04 Alexander Grund via Boost, < boost@lists.boost.org> wrote:
3. What benefit is there going from Doxygen (over multiple conversions)
to boostbook? Can't I just go from Doxygen to HTML?
So that you can cross-reference the Doxygen reference with whatever other documentation you have, which requires the whole documentation to eventually be in a single format (which is Boostbook).
And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Richard Hodges hodges.r@gmail.com office: +442032898513 home: +376841522 mobile: +376380212
On 1/1/20 4:03 AM, Richard Hodges via Boost wrote:
And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
Doxygen to XML, Renders Doxygen meta information in a form that it can be combined with something else. Presumable this is done by some Doxygen defined magic. XML to Boostbook - BoostBook is DocBook with a bunch of extra tags for handling C++ specific vocabulary types. The hope would be that this extra "semantic" information would permit facilities like better generation of things like better cross reference information, better formating of C++ "things" - like typenames vs variable names, vs examples, vs .... Boostbook can and does get created different ways: Doxygen, QuikBook, by hand, by XMLMind (in my case) and perhaps other ways I'm not familiar with. Not everyone actually uses BoostBook tags. Strictly speaking it is not necessary as it's an extension of DocBook. BoostBook->DocBook (xslt) - converts the special boostbook tags to more generic DocBook tags. DocBook -> html, pdf, etc.. (xslt, fop, ...) - renders the Docbook in a device specific format. So the question is: Which of the above steps is superfluous? Which do you think you can eliminated. Or do you want to consolidate them to eliminate steps? But composing the above steps is much simpler than than trying to do it in less steps. Time spent to execute the above steps is not significant in the scheme of things.
Other than the very pleasing boost documentation styling, is this seemingly convoluted conversion route necessary? Is it not possible to configure a Doxyfile to contain the correct styling?
I do not believe that Doxygen can be configured to capture semantics of much of C++ code to generated reference documentation. And of course that doesn't even touch upon other necessary things like narrative, examples, references, illustrations, etc.
I have no knowledge of the evolution of boost documentation and have no axe to grind, but as a newcomer it seems to me that there is a lot of 'unnecessary' compication in the production of documentation.
Right.
I appreaciate that there's no real sense in revisting existing libraries, but for new ones wouldn't it be prudent to choose the shortest possible path which involves the least learning and maintenance?
LOL - feel free to suggest another path. Robert Ramey
participants (6)
-
Alexander Grund -
Edward Diener -
Mathias Gaunard -
Rene Rivera -
Richard Hodges -
Robert Ramey