[LLVMdev] [RFC] Moving to Sphinx for LLVM and friends documentation (with partial implementation (in both 10pt and 12pt font)).

[David A. Greene]

OvermindDL1 <overminddl1 at gmail.com> writes:

> On Tue, Aug 10, 2010 at 1:09 PM, David A. Greene <greened at obbligato.org> wrote:
>> BoostBook/QuickBook is really cool but I found it nearly impossible to
>> use outside of the Boost tree.  In other words, a few years ago, at
>> least, it was intimately tied to the Boost project.  That may have
>> changed recently, I don't know.
>
> What of it is too tied to Boost?  Once compiled it is completely standalone.

It's been a while, but IIRC the doxygen integration relied on bjam
somehow, finding the tools perhaps?  The BoostBook XML files also
hard-code some assumptions about the project layout, IIRC.

If building the tool requires Boost.Build that is a pretty heavy burden.

> On Tue, Aug 10, 2010 at 1:09 PM, David A. Greene <greened at obbligato.org> wrote:
>> I also really hate the way QuickBook chops up and represents pages.  The
>> Table-of-Contents + prev/next links format is really terrible.  It's
>> very difficult to navigate non-linearly.
>
> Actually that is an option when you define your documentation, a
> simple single-line change can make it so it chops it up, or introduces
> it as a single mass page properly linked together by anchors, and
> there are many other patterns that can be done.  The Boosty way is
> just to chop it up, but if you notice, not all of the library's
> documentation does that.

Well, that's good news!  I know that various Boost libraries do it
different ways (compare MPL to Proto), but I've never found a scheme I
really liked.  Of course, that's personal preference, but ease of
navigation does matter.

> On Tue, Aug 10, 2010 at 1:09 PM, David A. Greene <greened at obbligato.org> wrote:
>> The QuickBook language is really nice for specifying documentation so if
>> we can fix the output format and make it work outside of Boost I'd be
>> all for using it.
>
> What output format issues do you have?  It is completely configurable,
> a single file can define a specific look for all of the documentation.

If that's true and we can make it do what we want, I'm all for
QuickBook.

> On Tue, Aug 10, 2010 at 2:10 PM, Douglas Gregor <dgregor at apple.com> wrote:
>> The BoostBook tool-chain is a total nightmare to configure and maintain. It produces decent, standards-style documentation and has a lot of great features, but the setup and learning curve is far too steep for me to recommend its use for LLVM.
>>
>>        - Original author of BoostBook
>
> It is difficult to set up, but once setup it never needs to be touched
> again, adding new pages are very simple, should not make it sound more
> difficult then it is.

But it should be possible for all of us to build LLVM's documentation
tools.  I really don't want to see bjam code in LLVM *shudder*.

It would be a great contribution if someone could port the
BoostBook/QuickBook build to make and completely divorce it from Boost
proper.  It's a tool a lot of projects could really use, IMHO.

                               -Dave