Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-09-29 13:24:53

On 28/09/11 17:09, John Maddock wrote:
>>> Perhaps quickbook to reStructuredText is a feasible solution.
>>> Then all move to writing in reStructuredText, etc.
>>
>> But then there's the issue of lossiness.
>
> And lets not forget that some of us really like quickbook ;-)

I do like quickbook too.
Although may intention was to discuss the workflow of documenting Boost,
I think I have identified what is the biggest pain to me: Doxygen
integration in BoostBook.

Doxygen is widely used C++ code documenting tool.
Fortunately or unfortunately, it is also used by many Boost authors.

Doxygen does not support many of the terms/concepts/elements used across
Boost libraries. It is also becasue it is almost impossible to document
them well at source code levels.
However, things like "concept and model" exist at source code level, so
authors try to do their best with Doxygen.
The resulting documentation is hopeless. It lacks of proper structure
and does not make sensible use of the Hypertext (no links between
properties of concept with properties of model). Examples:

www.boost.org/doc/libs/1_47_0/libs/geometry/doc/html/geometry/reference/concepts.html
http://www.boost.org/doc/libs/1_47_0/libs/pool/doc/index.html

Conclusion: there is no need for a tool that can handle X number of 
programming languages and output formats, but a tool that can handle C++ 
programming language very very well, especially its "modern" aspects.

So, authors invent custom processors and tools to integrate. We have:
- bits of support in QuickBook (BoostBook) e.g. xinclude autodoc.xml
- Perl scripts (e.g. ref_tag_fix.pl in DateTime)
- complex (KLOCs) XSL Doxygen->BoostBook|QuickBook translator(s)
- custom Doxygen to BoostBook converters written in C++ using external
XML libraries (sic!)

My initial attempt to Boost.Geometry docs was based on XSL (idea I
copied from Boost.Asio). It worked well, but...we dropped it because of
its complexity that would make maintenance (and contributions from new
hackers) very difficult, unless we assume everyone's got XSLT-fu.

I assume getting rid of Doxygen from Boost is not an option ;-)

So, I started to think about Sphinx as a foundation of C++ documentation
integrator/generator, inspired by the basic Sphinx API for Doxygen:

http://packages.python.org/sphinxcontrib-doxylink/index.html#confval-
doxylink
http://packages.python.org/sphinxcontrib-doxylink/index.html#confval-doxylink

Long story short, I'm looking for Boost-wide solution for:
- defiend workflow
- integrate source level documentation with documentation dedicated to
end-user
- squeeze all possible juices from Doxygen comments, add documentation
from other sources (e.g. .qbk files) and transform it to complete content
- make documentation looking well and consistent across Boost
- (wishful thinking about ideal) make documentation interlinking content 
across Boost libraries
- step-by-step guide on documenting Boost which fits on 1-2 sheets of A4 
printout, otherwise the process is too complex and hardly anyone will 
bother.

> Also some things like the Math docs have some complex quickbook
> templates for generating differing content for PDF and HTML output
> in order to support equations etc.

Sphinx can produce PDF and many more:

http://sphinx.pocoo.org/latest/builders.html

(I imagine many would like to read Boost docs in Kindle :-) or browse
it in QtHelp or Devhelp)

> Which is not to say that Boost.Build couldn't support
> RestructuredText to facilitate building such docs - then if they can
> be built as PDF's (I assume there's a way?) the Boost-wide PDF build
> could incorporate the Restructured Text docs as well as the Docbook
> ones.

I'm not trying to advocate reStructuredText in Boost.
I'm trying to seed the idea of powerful and extensible tool like Sphinx,
with no relation to this particular format.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org