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

[Michael Spencer]

On Mon, Aug 9, 2010 at 8: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.  :-)

That and BoostBook are all I had heard of either until Daniel popped
into the conversation and mentioned Sphinx.


===================================================================================================
I will also use this space to reply to OvermindDL1 instead of writing
two emails.

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.
* It requires boost-build, which is a rather complex dependency and
yet another full build system.
* It just feels really complex all around.

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



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

I was planning on stealing Daniel's layout from the LNT docs for now
(which are Sphinx based (I actually didn't know this until _after_ I
had done a bunch of work :P)), and mirror the colors from the llvm
logo. That's as far as my artistic skills go. I just want to make sure
people know I'm completely open to any suggestions.

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

I'll need help integrating it into the build system. As for
auto-update, I think Daniel (there's that name again) already has this
somewhat setup. Again I don't know how to do this.

>
>> #. 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).
>
> -Chris

Of course. I agree that it should be incremental. This really goes
with how this project should make its way into trunk. I was thinking
of making a docs/sphinx directory and putting {conf.py, index.rst, <a
few core docs>, _templates} in there. This will have no effect other
than adding the files. From there we can work on build system
integration and infrastructure.

The thing with "sphinxifying" is that a lot of it has to do with how
all of the documentation fits together, so it may be hard to get a
feel with only one doc. However, I think it would be a good idea to
start with just a few core docs (LangRef, GettingStarted{,VS}, ???)
and go from there.

- Michael Spencer