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

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

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

On Tue, Aug 17, 2010 at 4:50 PM, OvermindDL1 <overminddl1 at gmail.com>
wrote:
> 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...
>
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.

Keir

> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20100818/89502d39/attachment.html>

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