sphinx bug

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

sphinx bug

Ondrej Certik
Hi,

first, let me apologize, if this is not the correct mailinglist to
ask. Is there some mailinglist for the Sphinx project?

http://sphinx.pocoo.org/

I tried to go to the #python-docs channel, but it doesn't exist.
Anyway, the project is great. We moved the docs in ipython to it and
we are going to move sympy docs as well.

We found a bug though. If python-pygments isn't installed, sphinx
doesn't say anything, "make latex" hapilly generate a latex file, but
this latex file fails to compile:

! Undefined control sequence.
<argument> In \lb
                  []1\rb []: from ipython1.kernel import client
l.1205 ...rb[]: from ipython1.kernel import client

That's because the latex file is missing some definitions, like \lb,
that only get included when python-pygments is installed.

Do you think the file sphinx/highlighting.py line 30 could be fixed to
emit a large warning message, that the latex output will be broken
(possibly with an explanation of the problem)? That way one can easily
spot it and fix it.

Actually it took my 45 minutes of debugging with winpdb to figure out
what's wrong, because I had one computer where it worked and another
where it didn't. I compared all Debian latex packages on both, but it
didn't occur to me the problem could by in missing pygments. But I am
glad I figured this out. :)

Thanks a lot,
Ondrej
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: sphinx bug

Georg Brandl-2
Ondrej Certik schrieb:
> Hi,
>
> first, let me apologize, if this is not the correct mailinglist to
> ask. Is there some mailinglist for the Sphinx project?

Not right now. I guess the people on this list won't mind Sphinx traffic.

> http://sphinx.pocoo.org/
>
> I tried to go to the #python-docs channel, but it doesn't exist.

It does exist, at least on my Freenode server :)

> Anyway, the project is great. We moved the docs in ipython to it and
> we are going to move sympy docs as well.

That's great news! If you need anything, let me know.

> We found a bug though. If python-pygments isn't installed, sphinx
> doesn't say anything, "make latex" hapilly generate a latex file, but
> this latex file fails to compile:
>
> ! Undefined control sequence.
> <argument> In \lb
>                   []1\rb []: from ipython1.kernel import client
> l.1205 ...rb[]: from ipython1.kernel import client
>
> That's because the latex file is missing some definitions, like \lb,
> that only get included when python-pygments is installed.
>
> Do you think the file sphinx/highlighting.py line 30 could be fixed to
> emit a large warning message, that the latex output will be broken
> (possibly with an explanation of the problem)? That way one can easily
> spot it and fix it.

It's even easier to fix the markup so that it will work regardless of
Pygments installed or not.

> Actually it took my 45 minutes of debugging with winpdb to figure out
> what's wrong, because I had one computer where it worked and another
> where it didn't. I compared all Debian latex packages on both, but it
> didn't occur to me the problem could by in missing pygments. But I am
> glad I figured this out. :)

Thanks for the report! It's fixed in SVN trunk now (r61806).
Georg


--
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: sphinx bug

Ondrej Certik
>  > Anyway, the project is great. We moved the docs in ipython to it and
>  > we are going to move sympy docs as well.
>
>  That's great news! If you need anything, let me know.

Now I am figuring out how to use templates so that the search box is
available on all pages.

>  > We found a bug though. If python-pygments isn't installed, sphinx
>  > doesn't say anything, "make latex" hapilly generate a latex file, but
>  > this latex file fails to compile:
>  >
>  > ! Undefined control sequence.
>  > <argument> In \lb
>  >                   []1\rb []: from ipython1.kernel import client
>  > l.1205 ...rb[]: from ipython1.kernel import client
>  >
>  > That's because the latex file is missing some definitions, like \lb,
>  > that only get included when python-pygments is installed.
>  >
>  > Do you think the file sphinx/highlighting.py line 30 could be fixed to
>  > emit a large warning message, that the latex output will be broken
>  > (possibly with an explanation of the problem)? That way one can easily
>  > spot it and fix it.
>
>  It's even easier to fix the markup so that it will work regardless of
>  Pygments installed or not.

You mean in rst? I think we are using just regular ::

  some code

>
>
>  > Actually it took my 45 minutes of debugging with winpdb to figure out
>  > what's wrong, because I had one computer where it worked and another
>  > where it didn't. I compared all Debian latex packages on both, but it
>  > didn't occur to me the problem could by in missing pygments. But I am
>  > glad I figured this out. :)
>
>  Thanks for the report! It's fixed in SVN trunk now (r61806).

Thanks for the fix!

Ondrej
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: sphinx bug

Georg Brandl-2
Ondrej Certik schrieb:
>>  > Anyway, the project is great. We moved the docs in ipython to it and
>>  > we are going to move sympy docs as well.
>>
>>  That's great news! If you need anything, let me know.
>
> Now I am figuring out how to use templates so that the search box is
> available on all pages.

Try the latest trunk -- I'd forgotten to reenable the search box after
fixing the JS code.

>>  > We found a bug though. If python-pygments isn't installed, sphinx
>>  > doesn't say anything, "make latex" hapilly generate a latex file, but
>>  > this latex file fails to compile:
>>  >
>>  > ! Undefined control sequence.
>>  > <argument> In \lb
>>  >                   []1\rb []: from ipython1.kernel import client
>>  > l.1205 ...rb[]: from ipython1.kernel import client
>>  >
>>  > That's because the latex file is missing some definitions, like \lb,
>>  > that only get included when python-pygments is installed.
>>  >
>>  > Do you think the file sphinx/highlighting.py line 30 could be fixed to
>>  > emit a large warning message, that the latex output will be broken
>>  > (possibly with an explanation of the problem)? That way one can easily
>>  > spot it and fix it.
>>
>>  It's even easier to fix the markup so that it will work regardless of
>>  Pygments installed or not.
>
> You mean in rst? I think we are using just regular ::
>
>   some code

Sorry, I meant the generated LaTeX markup.

Georg

--
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: sphinx bug

Ondrej Certik
On Sun, Mar 23, 2008 at 10:13 PM, Georg Brandl <[hidden email]> wrote:

> Ondrej Certik schrieb:
>
> >>  > Anyway, the project is great. We moved the docs in ipython to it and
>  >>  > we are going to move sympy docs as well.
>  >>
>  >>  That's great news! If you need anything, let me know.
>  >
>  > Now I am figuring out how to use templates so that the search box is
>  > available on all pages.
>
>  Try the latest trunk -- I'd forgotten to reenable the search box after
>  fixing the JS code.

Excellent I tried it and it works like a charm - both the search box
and the :role: stuff.

Thanks a lot. Do you think you could please make a release? It's more
convenient to download and extract a tarball, than play with svn.

Ondrej
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig