Re: Recomended way of generating documentation

From: Edward Diener (eldiener_at_[hidden])
Date: 2019-12-29 14:20:55

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.