Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-04 23:13:54

on Tue Oct 04 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:

> On 02/10/11 23:03, Dave Abrahams wrote:
>> on Thu Sep 29 2011, Mateusz Loskot <mateusz-AT-loskot.net> wrote:
>>>
>>> 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,
>>   do not?---------------------------------^
>>
>> That's true of concepts unless you're using Boost.ConceptCheck.  But
>> even so, they will only be seen by Doxygen as regular C++ and not as the
>> abstractions they represent.  And there are no model declarations. :-(
>
> I understand your question, but I meant it as it reads.
> I assumed concepts have representation in C++ code, either using
> Boost.ConceptCheck or custom implementation of concepts.

Yes, they could.  And we could #ifdef them out for tools (like existing
C++ compilers) that don't support them.

> So, I assumed they are documented and linked with corresponding
> models.  

Generally speaking, models of auto concepts and of concepts matched by
concept_map templates won't have any explicit link to the concept.

>>> 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.
>> 
>> Yeah, it's nasty.
>
> It is, but this particular implementation for Boost.Asio gives
> best output I've seen so far, e.g.
>
> http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/async_read.html

Yeah, not bad.

>>> Long story short, I'm looking for Boost-wide solution for:
>>> - defined workflow
>> 
>> Could you be more specific about what kind of workflow you have in mind?
>
> Yes, the idea may seem vague indeed.
> I mean overall set of well described conventions and tools to write and
> process complete documentation of a Boost library. Complete means as
> covering all aspects of Boost C++ library, including concepts.
> Best practices and recommendations are also put in to the workflow
> definition. The workflow definition in short:
> - markup to use (Doxygen, BoostBook, QuickBook, ..)
> - content processing depends on input (the markup used)
> - BoostBook as common "raw" format later used as input for publishing
>   processors (HTML, PDF, .etc.)
> - framework of content structure of Boost library (and libraries together)
> - content integration into Boost documentation

OK

>>> - integrate source level documentation with documentation dedicated to
>>>   end-user
>> 
>> Again, could you be more specific?  Is it deeper than simply allowing
>> linking between the two?
>
> Yes, I made it utterly unclear.
> I meant what I have explained above now. It is to use source code
> comments content as documentation content too, including interlinking
> symbols (also concepts with models).
>
> Simply, documentation of Boost.Asio is a good incarnation of the idea.

OK.  IMO you should think about literate programming as well in this
design space.

>>> - 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
>> 
>> Yeah, that would indeed be beautiful.
>
> Yes. Shortly explained above already, it would mean accepting several
> documentation sources/formats as input and producing BoostBook.

That can be done.

>>>> 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.

See http://www.mathjax.org/
I think that's probably the best technology for HTML math at this point.

>>> Sphinx can produce PDF and many more:
>>>
>>> http://sphinx.pocoo.org/latest/builders.html
>> 
>> (note: you'd need to pass through LaTeX as an intermediate format;
>> Unless something has changed since I last look the reportlab stuff is
>> geared to forms and is hopelessly weak when it comes to anything that
>> needs real page layout/line breaking.  That's what we did for C++
>> Template Metaprogramming).
>
> I see. I don't know if anything has changed. I have seen a few printouts
> and they looked "not bad" though.

Yeah, one or two pages, right?  Or the page breaks were explicit?

Listen, you simply can't beat LaTeX for producing beautiful printed
documentation or PDFs.  IMO there's no point in trying to avoid it.  FOP
is a nightmare (or was, last time I looked, even version 2).

>> What's the solution?  I think someone needs to survey the kinds of
>> things people are doing with QuickBook and BoostBook, so that we can
>> assess whether other systems can support our needs.
>
> I'm willing to help with this.
> Can we make a list of questions ("the kind of things") do we want to
> answer with the survey?
>
>> And while we're discussing alternate markup, I'd like to throw Markdown
>> and Org-mode into the ring.
>
> AFAIU, reStructuredText is extensible so it is possible to add custom
> directives. 

Yes, but they're often a bit cumbersome.

> Markdown is not, but it's light.

In addition to being able to do a few things that ReST cannot (the
converse is also true), it's *very* widely-used, a fact which should not
be taken lightly.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com