Recomended way of generating documentation

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Recomended way of generating documentation

Boost - Dev mailing list
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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Recomended way of generating documentation

Boost - Dev mailing list
On Sun, Dec 29, 2019 at 7:05 AM Alexander Grund via Boost <
[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Recomended way of generating documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Recomended way of generating documentation

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Sun, 29 Dec 2019, 14:04 Alexander Grund via Boost, <[hidden email]>
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
Reply | Threaded
Open this post in threaded view
|

Re: Recomended way of generating documentation

Boost - Dev mailing list
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 <
[hidden email]> wrote:

> On Sun, 29 Dec 2019, 14:04 Alexander Grund via Boost, <
> [hidden email]>
> 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
[hidden email]
office: +442032898513
home: +376841522
mobile: +376380212

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Recomended way of generating documentation

Boost - Dev mailing list
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



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost