Re: [boost] Generating Boost documentation with pandoc

Subject: Re: [boost] Generating Boost documentation with pandoc
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2017-01-16 07:13:58

On 16.01.2017 03:39, Vinícius dos Santos Oliveira wrote:
> 2017-01-08 13:07 GMT-03:00 Stefan Seefeld <stefan_at_[hidden]>:
>
>>> Gonna use asciidoc to write my next documentation so I can still have
>>> DocBook (not sure why it's so important) and have free ePUB support.
>>> asciidoc or any other simple markup language that does the job.
>> (I'm actually pondering to move the Boost.Python docs from QuickBook to
>> good old ReST, so I could manage all its documentation with the sphinx
>> tool (used by most projects in the Python community). It may lack some
>> features, but the fact that it is well-known by many people outweighs
>> that by far.
>> Boost still has a long way to go to get out of the NotInventedHere mood...
>
> I converted mine to asciidoc already:
> https://github.com/BoostGSoC14/boost.http/commit/c535bf73cab03b60b285df7e7bff62c49be99744
>
> It'll be interesting to see you converting document to reStructuredText and
> compare results/share experiences.

I put a lot of effort into converting the original HTML into QuickBook
two years ago, but I expect the conversion from QuickBook to ReST to be
almost trivial.

For the new Boost.Python NumPy extension the documentation already was
using sphinx / ReST, so all I needed to do is slightly adjust the
template to match the Boost format (more or less: see
http://boostorg.github.io/python/doc/html/numpy/index.html)

What I like about sphinx is its support for superstructure, i.e. the
simplicity to combine documents into larger documents (including
websites), as well as its templating support (to customize styling).

And of course, the tool is widely known and used (all the Python
community is using it), so neither do I have to solve all the bugs
myself, nor write documentation. :-)

        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...