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

Michael Spencer bigcheesegs at gmail.com
Tue Aug 17 15:32:49 PDT 2010


On Sat, Aug 14, 2010 at 8:21 PM, OvermindDL1 <overminddl1 at gmail.com> wrote:
> On Thu, Aug 12, 2010 at 5:52 PM, Aaron Gray <aaronngray.lists at gmail.com> wrote:
>> poke !
>
> I whipped up a quick example, this is a total of about an hour of work
> due to finding parameters to set it up, once that is finished though
> the actual documentation is simple.
>
> Look in the html subdirectory to see the generated html as separate
> files, but it can also generate a single large html file, pdf, man
> pages, docbook, whatever.
>
> The source qbk files and Jamroot is included, but it would be a cinch
> to have CMake build it instead.  If you do:
>  bjam -n html
> then it will not build it, but it outputs all of the commands and
> everything it does, which is surprisingly little, so yes, it could be
> integrated with ease.
>
> I ported the first two chapters of the C++ Kaleidoscope tutorial to
> it.  I used the standard boost-style setup, except as an example I
> changed the section headers to be LLVM-doc style, was simple.  The
> boost standard DTD and XSL and such files can be edited to change
> style as necessary as well, but CSS should work for the bulk.  I did
> not bother changing style of much, but to have autogenerated TOC at
> the top of those would be a single option change, etc...  Many things
> can be done, and as you can see the documentation style of the qbk
> files is simple, and C++ and such is auto color coded, although that
> could be disabled if wanted.
>
> To show how the documentation can stay in sync with the source, I
> included the Kaleidoscope source in the example and I edited the
> Chapter 2 source to add a few lines of markup to let it pull in the
> source automatically so the documentation is always in sync with the
> source as they are one and the same.  I also showed how to link to the
> cpp source instead of embedding it at the bottom of Chapter 2, but
> that could be done as well if needed.
>
> I have all the chapter's in there, but the rest are empty, I just
> included them to let all the links work.
>
> If there is a specific example that you want demonstrated, just say.
>
> To build the example yourself, just put the two qbk files and the
> Jamroot in a directory, make sure you have boost's quickbook and
> boostbook built, then just do:
>  /path/to/bjam
> and it will build the multi-part html by default, or of course do:
>  /path/to/bjam -n
> to see what it is doing instead, which basically involves just
> creating a system-customized link to the dtd and xsl and such
> directories in boostbook (if LLVM used this then you would include
> those in LLVM itself, probably customized, and the manifest would not
> need to be system-generated-specific each time, it would be static),
> then calling quickbook, then calling xsltproc twice, quite simple, and
> I have ran the steps manually myself to confirm they work, and they
> do.

Thanks for setting this up, I didn't even attempt to use boostbook. I
like the quickbook syntax.

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.

Sphinx can include a file as source code. It is also extensible in
python by simply adding a python file and adding a reference to it in
the config file.

- Michael Spencer




More information about the llvm-dev mailing list