[llvm-commits] [PATCH] LLVM FAQ converted into reST format

[Mikael Lyngvig]

A quick one - why does Sphinx complain about this?

c:\Synology\LLVM\llvm-trunk\docs\index.rst:60: WARNING: toctree contains
reference to nonexisting document u'faq'

I added "faq" to the toctree section of index.rst.  If I don't do it, I get
an error about the FAQ not being in any toctree.  I've played around with
it for 20 minutes without finding a solution.

2012/6/16 Sean Silva <silvas at purdue.edu>

> I don't know what's happening with the "#." stuff. The sphinx reST primer
> even gives that as an example, so maybe it is something in the LLVM sphinx
> configuration.
>
> I would hold off on putting the FAQ at the top of the index. That change
> can be made later if there is a perceived need.
>
> > The C backend change never made it into the reST file because it was a
> manually written TOC entry without any text block.
> Good to see that you are on top of this :)
>
> Other than some 80-column violations this LGTM.
>
> For the final patch, you should probably include the following three
> things:
> 1. add the FAQ.rst file that we've been looking at here
> 2. remove the FAQ.html file
> 3. link this file into a toctree (to avoid Sphinx warnings)
>
> --Sean Silva
>
>
> On Fri, Jun 15, 2012 at 2:50 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>
>> The numbered lists are driving me crazy!  No matter what I try, they end
>> up being numbered 1, 1, 1, and not 1, 2, 3.  Do you have any experience
>> with this?  The embedded bulletted list shows up properly.  I use #.
>> because I prefer that to 1. I could number the list manually, but that kind
>> of defeats the whole purpose of using Sphinx (IMHO).  This is about the
>> numbered list in the "I'd like to write a self-hosting compiler..." section.
>>
>> I'll munge about and try not to create havoc (sometimes I feel like an
>> elephant in a glass retail store).
>>
>> The C backend change never made it into the reST file because it was a
>> manually written TOC entry without any text block.
>>
>>
>> 2012/6/15 Sean Silva <silvas at purdue.edu>
>>
>>> Hi Mikael,
>>>
>>> It seems like the ugly underlining that Michael mentioned is actually a
>>> CSS problem and not a document structure problem. Michael Spencer and I
>>> are working on updating the CSS to avoid it.
>>>
>>> Also, you should prepare this as a patch that creates the reST file and
>>> removes the FAQ.html file and links the reST FAQ into the main toctree
>>> somehow, in order to avoid the conflict between FAQ.html and the generated
>>> FAQ.rst -> FAQ.html.
>>>
>>> btw, there was a recent change I caught out of the corner of my eye to
>>> the FAQ removing references to the C backend. Could you doublecheck to make
>>> sure that those changes get pulled into your reST version? Thanks.
>>>
>>> --Sean Silva
>>>
>>> On Fri, Jun 15, 2012 at 1:46 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>>>
>>>> I don't seem to be able to make it fit in 80 chars.  For instance, the
>>>> numbered lists require more than 80 chars and Sphinx won't accept them if
>>>> they are broken into multiple lines.  The same goes for the questions:
>>>> Several Sphinx commands must fit within a line for Sphinx to accept them.
>>>>  I've tried backquoting the end-of-line character (text text text \), but
>>>> that didn't work either.
>>>>
>>>> It all looked very nice in my end, but I didn't use the LLVM
>>>> configuration of Sphinx as I don't know where to get it from.
>>>>
>>>> I got some pointers to the SVN repository for the FAQ, but the first
>>>> didn't include the FAQ and the second gave me a cycle while trying an SVN
>>>> pull.  What URL do you use to pull out the documentation for LLVM?
>>>>
>>>> 2012/6/15 Michael Spencer <bigcheesegs at gmail.com>
>>>>
>>>>> On Fri, Jun 15, 2012 at 2:25 AM, Mikael Lyngvig <mikael at lyngvig.org>
>>>>> wrote:
>>>>> > Can't really make a patch file as it is a new file based on FAQ.html
>>>>> from
>>>>> > the website.
>>>>> >
>>>>> > Changes are:
>>>>> >
>>>>> >    1. The format is now reST instead of HTML.
>>>>> >    2. A few (like two or three) missing code markups have been added.
>>>>> >    3. Sphinx code-blocks are now used for all kinds of code: bash,
>>>>> c, and
>>>>> > llvm.
>>>>> >
>>>>> > Other than that, the file should be a faithful and precise
>>>>> conversion from
>>>>> > HTML to reST.
>>>>> >
>>>>> >
>>>>> > Cheers,
>>>>> > Mikael
>>>>>
>>>>> It needs to be 80-col except for underlined headers. Also it needs to
>>>>> be linked from a toctree and properly integrated. It also currently
>>>>> conflicts with the FAQ.html that gets copied in so I had to rename it
>>>>> to even see what it looked like.
>>>>>
>>>>> Each header is currently getting underlined by Sphinx, this looks
>>>>> pretty weird. It should be using a different header level.
>>>>>
>>>>> - Michael Spencer
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> llvm-commits mailing list
>>>> llvm-commits at cs.uiuc.edu
>>>> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>>>>
>>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120616/b802c48a/attachment.html>