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

[Douglas Gregor]

On Aug 9, 2010, at 6:22 PM, OvermindDL1 wrote:

> On Mon, Aug 9, 2010 at 6:51 PM, Chris Lattner <clattner at apple.com> wrote:
>> 
>> On Aug 8, 2010, at 11:29 PM, Michael Spencer wrote:
>>> 
>>> What Do You Think?
>>> ------------------
>>> 
>>> I realize that changing the documentation format is non-trivial, but I believe
>>> that the benefits are worth the effort. If we go forward with this I will finish
>>> the first two points above and work to integrate doxygen and keep everything
>>> running smoothly.
>> 
>> I strongly support this.  I've been interested in moving the documentation over to a better system for a long time, but the only decent one I've known about was docbook, which is ... a bit more complicated than I hoped we'd need.  :-)
>> 
>>> What's Left?
>>> ------------
>>> 
>>> #. Pick the paint color for the bike shed. I have done no work on this other
>>>   than copying over the default ``sphinxdoc`` theme to the source dir as
>>>   ``llvm-theme``. Creating Sphinx themes is actually rather easy, so anyone is
>>>   welcome to take a stab at this if they wish.
>> 
>> I suggest you just dictate what you think the right thing is, asking for and ignoring or responding to feedback as you think is best.  Don't try to make everyone happy.  I agree with Vikram that there are some major formatting issues that should be fixed before this is rolled out.
>> 
>>> #. Integrate building the docs into the autoconf and CMake build systems.
>> 
>> Yes, this seems important.  Also, the web page needs to auto-update the docs in response to commits.
>> 
>>> #. Finish moving over the docs.
>>> #. Finish Sphinxifying them.
>> 
>> Can this be done incrementally?  It would be great to start with one doc (like LangRef) and make it really really good and get the infrastructure right, then move on to other docs (which others might help out with).
> 
> 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.


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