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

On Tue, Aug 17, 2010 at 11:09 PM, David A. Greene <greened at
obbligato.org> wrote:
> Please do.  7z is not supported on Linux.
Does not this work?
http://packages.debian.org/lenny/p7zip-full

Eugene

On Tue, Aug 17, 2010 at 4:06 PM, David A. Greene <greened at
obbligato.org> wrote:
> 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.
None of them rely on bjam, bjam just knows the commands, but as stated
you can use:
  bjam -n
to see the exact commands it runs and everything it does, very easy to
call from CMake, and in fact the CMake build system port for Boost
does handle that already.  So no, it does not at all require
Boost.Build.


On Tue, Aug 17, 2010 at 4:06 PM, David A. Greene <greened at
obbligato.org> wrote:
>
>> 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.
As mentioned above, the BoostBook part does not compile anything, it
just downloads and sets up the BoostBook look and feel, which you can
easily change all as you wish.


On Tue, Aug 17, 2010 at 4:06 PM, David A. Greene <greened at
obbligato.org> wrote:
>> 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.
It is all possible, and as stated it will require a touch of setup for
the CMake part, but there is already a CMake port to replace bjam for
building Boost that knows about that, as well as I know exactly what
commands bjam runs and I have run them myself and they are very
simple, all but 3 application calls, very simple.


On Tue, Aug 17, 2010 at 4:06 PM, David A. Greene <greened at
obbligato.org> wrote:
>> 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.
QuickBook itself uses Boost.Spirit as the parser and the regex engine
inside Boost, to separate that from Boost 'would' be difficult, except
there exists a nice little Boost tool call "bcp".  What bcp can do is
pull out parts of Boost that a project requires out into a specific
location, even changing the boost namespace to something else if you
wish to prevent collisions should someone use Boost itself of a
different version.  As an example, if LLVM decided to use Boost in it,
say they decided to use Boost.Spirit.Qi as the parser engine for
tablegen instead of bison or whatever, they could run bcp on the LLVM
source and it pulls out the necessary Boost source/headers/etc... that
is necessary to compile it (again, changing the boost namespace to
something else if you want).

So, yes, you could divorce it from Boost, and the license fully allows it.

QuickBook is the only part that would need to be compiled, the
BoostBook part is not a program but the 'look and feel' of the
documentation, which you can put anywhere that you want, and of course
change to look like anything that you want.




On Tue, Aug 17, 2010 at 4:09 PM, David A. Greene <greened at
obbligato.org> wrote:
> OvermindDL1 <overminddl1 at gmail.com> writes:
>
>> Correction, even the zip by itself is too big, here is the 7z, if
>> someone wants a giant zip, I can host it somewhere...
>
> Please do.  7z is not supported on Linux.  I would love to take a look
> at this, but I can't.  :(
7z is supported just fine on Linux, I use it all the time, and it
compresses text like that a heck of a lot better then zip (about a 4:1
ratio).  But I will still put the zip up on my server, now at url:
  http://www.overminddl1.com/stuff/llvm_doc.zip




On Tue, Aug 17, 2010 at 4:32 PM, Michael Spencer <bigcheesegs at
gmail.com> wrote:
> Thanks for setting this up, I didn't even attempt to use boostbook. I
> like the quickbook syntax.
>
> I finally got around to trying this out on my windows machine. The
> problem is that you have to have a full boost installation so that you
> can compile quickbook and boostbook as there are no packaged binaries.
> There are also 3 other packages you have to install.
You need to compile quickbook, but as stated above that could easily
be put into LLVM itself so there are no dependencies to download with
regards to Boost.  boostbook is not something you compile, but rather
the look and feel infrastructure for the xsltproc compiler (the only
dependency you would need to get, basically docbook), and you would
just copy that into the LLVM tree and edit it to suit to taste.  The
only other dependency you would have is if you want to build pdf's.


On Tue, Aug 17, 2010 at 4:32 PM, Michael Spencer <bigcheesegs at
gmail.com> wrote:
> Sphinx can include a file as source code. It is also extensible in
> python by simply adding a python file and adding a reference to it in
> the config file.
Can you whip up an example like the first two tutorial chapters like I
did so we have a comparison?  With links to the source as the code
blocks so it would always stay in sync?  It would be good to have a
comparison, I could be easily swayed if necessary.

On Aug 17, 2010, at 3:42 PM, OvermindDL1 wrote:
> 
> On Tue, Aug 17, 2010 at 4:09 PM, David A. Greene <greened at
obbligato.org> wrote:
>> OvermindDL1 <overminddl1 at gmail.com> writes:
>> 
>>> Correction, even the zip by itself is too big, here is the 7z, if
>>> someone wants a giant zip, I can host it somewhere...
>> 
>> Please do.  7z is not supported on Linux.  I would love to take a look
>> at this, but I can't.  :(
> 
> 7z is supported just fine on Linux, I use it all the time, and it
> compresses text like that a heck of a lot better then zip (about a 4:1
> ratio).  But I will still put the zip up on my server, now at url:
>  http://www.overminddl1.com/stuff/llvm_doc.zip
Requiring people to get and install boost to work on docs is a non-starter.

What is wrong with sphinx?

-Chris

Eugene Toder <eltoder at gmail.com> writes:
> On Tue, Aug 17, 2010 at 11:09 PM, David A. Greene <greened at
obbligato.org> wrote:
>> Please do.  7z is not supported on Linux.
>
> Does not this work?
> http://packages.debian.org/lenny/p7zip-full
Apparently it is not available on the version of SuSE I have.

                             -Dave

OvermindDL1 <overminddl1 at gmail.com> writes:
>> 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.
>
> QuickBook itself uses Boost.Spirit as the parser and the regex engine
> inside Boost, to separate that from Boost 'would' be difficult,
except
> there exists a nice little Boost tool call "bcp".  What bcp can
do is
I actually meant "Boost.Build" here.  Sorry for creating the
confusion.
QuickBook using Spirit is fine.
>> I finally got around to trying this out on my windows machine. The
>> problem is that you have to have a full boost installation so that you
>> can compile quickbook and boostbook as there are no packaged binaries.
>> There are also 3 other packages you have to install.
>
> You need to compile quickbook, but as stated above that could easily
> be put into LLVM itself so there are no dependencies to download with
> regards to Boost.  boostbook is not something you compile, but rather
> the look and feel infrastructure for the xsltproc compiler (the only
> dependency you would need to get, basically docbook), and you would
> just copy that into the LLVM tree and edit it to suit to taste.  The
> only other dependency you would have is if you want to build pdf's.
I really don't want to see us copying external project code into LLVM.
That becomes a nightmare.  Relying on a packaged version of
Quickbook/Boostbook is fine, as long as such a package is available, but
at the moment, it isn't.

I wasn't advocating that we _must_ build Boostbook/Quickbook as part of
LLVM, only that developers should be able to easily rebuild the
documentation tools if necessary.  Those tools should live separately
from LLVM.  Putting Boostbook/Quickbook in the Boost tree is what
gave us the mess it's in now.  We shouldn't make that mistake again.

                             -Dave