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

Chris Lattner clattner at apple.com
Mon Aug 9 17:51:13 PDT 2010


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

-Chris



More information about the llvm-dev mailing list