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

[OvermindDL1]

Correction, even the zip by itself is too big, here is the 7z, if
someone wants a giant zip, I can host it somewhere...

On Sat, Aug 14, 2010 at 6:49 PM, OvermindDL1 <overminddl1 at gmail.com> wrote:
> The zip format was too big to fit through the moderator queue, so here
> is another with just the zip by itself (although the 7z is only
> 29kb...).
>
> On Sat, Aug 14, 2010 at 6:29 PM, OvermindDL1 <overminddl1 at gmail.com> wrote:
>> Helps if I attach the files...
>> Attached a zip for those that like the huge format, and a 7z for those
>> that like tiny formats.
>>
>> On Sat, Aug 14, 2010 at 6: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.
>>>
>>
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: llvm_doc.7z
Type: application/octet-stream
Size: 29309 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20100814/e839ce00/attachment.obj>