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

OvermindDL1 <overminddl1 at gmail.com> writes:
> On Tue, Aug 17, 2010 at 5:25 PM, Chris Lattner <clattner at
apple.com> wrote:
>> 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?
>
> They would not need to, as stated, it is simple to take what is needed
> thanks to bcp, only thing needed is docbook, which is a *lot* more
> prevalent than Sphinx and more well known.  The useful thing about
> quickbook over Sphinx is it is designed for C++ project documentation
> in a variety of formats, from html pages, single html document, pdf,
> man pages, straight docbook, etc...
What he said.

And the fact that Boostbook knows how to import Doxygen XML output is a
killer feature.  Having a hardcopy of the Doxygen reference can be
really useful.

I agree with Chris that at the moment, BoostBook/QuickBook is too hard
to set up.  I'm certainly not about to use bcp magic and litter my
workspace with it.  Get it packaged separately and it's a winner, I
think.  A nice Debian package would do wonders.

                                -Dave

On Aug 18, 2010, at 4:01 PM, David A. Greene wrote:
> And the fact that Boostbook knows how to import Doxygen XML output is a
> killer feature.  Having a hardcopy of the Doxygen reference can be
> really useful.
> 
> I agree with Chris that at the moment, BoostBook/QuickBook is too hard
> to set up.  I'm certainly not about to use bcp magic and litter my
> workspace with it.  Get it packaged separately and it's a winner, I
> think.  A nice Debian package would do wonders.
I'm not interested in solving boostbook's issues here.  I'm
interested in getting the documentation in llvm to suck less.  The shortest and
best path seems to be through sphinx.

-Chris

On Wed, Aug 18, 2010 at 3:40 AM, Keir Mierle <mierle at gmail.com>
wrote:
> Just a random observation from the Python world: Once Sphinx started taking
> over as the dominant documentation tool, the quality of Python
documentation
> greatly improved. This is not just because sphinx produces well formatted
> docs; it appears that the real driver behind the improvement is that
writing
> docs with sphinx / ReST is pleasant and easy, so more people do it.
I have noticed the same with quickbook, basically all new Boost
documentation is using it instead, and some older libraries are moving
over to it as well, it is just so much easier to use then what they
had been, and it even has a converter from html to quickbook for a
simple and quick conversion.


On Wed, Aug 18, 2010 at 4:55 PM, David A. Greene <greened at
obbligato.org> wrote:
> 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.
Actually Boost.Build/bjam does not depend on boost at all, not even
the source code as it is pure C, not even C++, to allow for the lowest
common denominator (although there is talk of a Boost.Build2 being
made in Python), and running it does not involve even needing Boost
installed, just a Jamroot in your projects directory that is properly
setup, kind of like a CMakeList(s?).txt for CMake.


On Wed, Aug 18, 2010 at 4:55 PM, David A. Greene <greened at
obbligato.org> wrote:
>>> 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.
Most people I would wager have Boost installed anyway, building
quickbook is as simple as navigating to its directory and typing
"bjam", but as stated above, it would be quite simple to separate it
from Boost for auto-compilation inside LLVM if you wished.


On Wed, Aug 18, 2010 at 5:01 PM, David A. Greene <greened at
obbligato.org> wrote:
> OvermindDL1 <overminddl1 at gmail.com> writes:
>
>> On Tue, Aug 17, 2010 at 5:25 PM, Chris Lattner <clattner at
apple.com> wrote:
>
>>> 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?
>>
>> They would not need to, as stated, it is simple to take what is needed
>> thanks to bcp, only thing needed is docbook, which is a *lot* more
>> prevalent than Sphinx and more well known.  The useful thing about
>> quickbook over Sphinx is it is designed for C++ project documentation
>> in a variety of formats, from html pages, single html document, pdf,
>> man pages, straight docbook, etc...
>
> What he said.
>
> And the fact that Boostbook knows how to import Doxygen XML output is a
> killer feature.  Having a hardcopy of the Doxygen reference can be
> really useful.
That is definitely true, not a feature I have used yet but I know some
libraries (like ASIO) do it to completely document everything that
they do not explicitly handle.


On Wed, Aug 18, 2010 at 5:01 PM, David A. Greene <greened at
obbligato.org> wrote:
> I agree with Chris that at the moment, BoostBook/QuickBook is too hard
> to set up.  I'm certainly not about to use bcp magic and litter my
> workspace with it.  Get it packaged separately and it's a winner, I
> think.  A nice Debian package would do wonders.
With what I have so far, it would involve this:

1) Download Boost of course if you do not already have it.
2) Navigate to the boost root directory
3) Run bootstrap.sh/bootstrap.bat (whether unix/windows) to build bjam
4) Navigate to BOOST_ROOT/tools/quickbook
5) Run ../../bjam (or bjam install to install it or whatever, put
quickbook on your path for easiest use if you want, not assuming that
for the rest of this though).
6) Install docbook (using aptitude, source, windows distributions,
boost's easy-install-but-slightly-broken-script, etc...)
7) Navigate to the LLVM doc directory (or if put into LLVM itself,
just the root LLVM directory).
8) Supply to the CMake gui or wizard or however you want to, the
location to quickbook and xsltproc
9) Make it, if the above paths are supplied to CMake, then it would
auto-build the documentation along with LLVM, or do "make docs" if you
gave it its own build type, or however you want to do it.

It is not really as involved as the number of steps indicate, I was
just breaking it down as much as possible.  No bcp is used in this
regard and quickbook is not included with LLVM but is required to be
built separately.

If you did bcp it into the LLVM area, into a tools directory or
something (what is littered?!?), then just the only steps you need are
6, 7, and 9, just installed docbook, navigate to LLVM and build it.



On Wed, Aug 18, 2010 at 5:03 PM, Chris Lattner <clattner at apple.com>
wrote:
>
> On Aug 18, 2010, at 4:01 PM, David A. Greene wrote:
>
>> And the fact that Boostbook knows how to import Doxygen XML output is a
>> killer feature.  Having a hardcopy of the Doxygen reference can be
>> really useful.
>>
>> I agree with Chris that at the moment, BoostBook/QuickBook is too hard
>> to set up.  I'm certainly not about to use bcp magic and litter my
>> workspace with it.  Get it packaged separately and it's a winner, I
>> think.  A nice Debian package would do wonders.
>
> I'm not interested in solving boostbook's issues here.  I'm
interested in getting the documentation in llvm to suck less.  The shortest and
best path seems to be through sphinx.
We would not use boostbook at all, just quickbook, which would then
use docbook.  Boostbook is just the look and feel of the boost
documentation, LLVM would have its own of course, hence no using of
boostbook.  Look above to see the most complicated method of building.