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

OvermindDL1 overminddl1 at gmail.com
Thu Aug 12 15:53:37 PDT 2010


On Mon, Aug 9, 2010 at 11:29 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> You are right that BoostBook is targeted directly for large C++
> projects, and I seriously considered BoostBook for this project, but
> ran into a few road blocks.
>
> * It's tightly integrated into boost and makes quite a few assumptions
> about that.

What assumptions is that?


On Mon, Aug 9, 2010 at 11:29 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> * It requires boost-build, which is a rather complex dependency and
> yet another full build system.

How does it require it?  I have used it directly before, without
boost-build (even if you wanted to simplify its use by calling it
using boost-build, it is not like it is CMake; boost-build, once
compiled, is a single executable, it requires no other files).


On Mon, Aug 9, 2010 at 11:29 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> * It just feels really complex all around.

Complex how so?  It is 'interesting' to set up, but once set up it is
extremely simple.  As well as the fact that to do some things in it
would be extremely simple compared to Sphinx which would not even
support the ability, such as the simple example of pulling in part of
some source code into the documentation straight from a compilable
source file, how would you do that with Sphinx?  Plenty of other
examples too.


On Mon, Aug 9, 2010 at 11:29 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> In the end I felt that there would be too much resistance to
> boost-build and the complexity. I then discovered Sphinx and found
> that it did everything I wanted and just felt clean and simple.


On Tue, Aug 10, 2010 at 1:09 PM, David A. Greene <greened at obbligato.org> wrote:
> OvermindDL1 <overminddl1 at gmail.com> writes:
>
>> BoostBook is a simplification of DocBook, with many things specific
>> for C/C++ source.  it can pull in parts of a source file so the doc
>> examples always show examples of code that is actually tested, it has
>> proper links to source code files, can integrate with doxygen with a
>> bit of work, can export to html, pdf, and a few other things...  I
>> like Sphinx, a lot actually, but BoostBook is more designed for this
>> kind of project.
>
> 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.


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.


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.


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.



More information about the llvm-dev mailing list