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

OvermindDL1 overminddl1 at gmail.com
Sat Aug 14 17:21:01 PDT 2010


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.



More information about the llvm-dev mailing list