From joe at bitworking.org Thu Mar 6 05:35:28 2008 From: joe at bitworking.org (Joe Gregorio) Date: Wed, 5 Mar 2008 23:35:28 -0500 Subject: [Doc-SIG] Standalone Sphinx Message-ID: <3f1451f50803052035r3688ef78u7ce1b6efa48ef4ad@mail.gmail.com> I'd like to document httplib2[1] using Sphinx as a step toward getting it into the standard library. When I searched the archives I only found a message from last September[2] that indicated it wasn't separable from Python 2.6/3.0 yet. Is that still the case? Thanks, -joe [1] http://code.google.com/p/httplib2 [2] http://mail.python.org/pipermail/doc-sig/2007-September/003660.html -- Joe Gregorio http://bitworking.org From g.brandl at gmx.net Sat Mar 8 21:17:10 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sat, 08 Mar 2008 21:17:10 +0100 Subject: [Doc-SIG] Standalone Sphinx In-Reply-To: <3f1451f50803052035r3688ef78u7ce1b6efa48ef4ad@mail.gmail.com> References: <3f1451f50803052035r3688ef78u7ce1b6efa48ef4ad@mail.gmail.com> Message-ID: Joe Gregorio schrieb: > I'd like to document httplib2[1] using Sphinx as a step > toward getting it into the standard library. When I searched > the archives I only found a message from last September[2] > that indicated it wasn't separable from Python 2.6/3.0 yet. > Is that still the case? No, it should now be completely usable for other projects. The documentation is still somewhat lacking, but I'm working on this. Just mail me if you have more questions. 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. From g.brandl at gmx.net Fri Mar 21 18:39:37 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Fri, 21 Mar 2008 18:39:37 +0100 Subject: [Doc-SIG] Sphinx released to PyPI Message-ID: I'm delighted to announce that the Sphinx library, used to build the new Python documentation (for 2.6 and 3.0) [1], is now released for general use. What is it? =========== Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText source files). Its website is at . What does it do? ================ Sphinx is not an API documentation generator like Epydoc. Instead, its focus is on hand-written documentation, such as the Python one. * Main output formats: HTML (including HTML Help) and LaTeX * Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information * Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children * Automatic indices: general index as well as a module index * Code handling: automatic highlighting using the Pygments highlighter * Goodies such as changes overview, and external link checking What else? ========== Various extensions are available and in development: * autodoc: pulls in documentation from docstrings that are written in reST, to avoid having to maintain multiple documentation locations * doctest: automatically tests snippets in the documentation in doctest fashion * coverage: documentation coverage checker Cheers, Georg [1] http://docs.python.org/dev -- 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. From ondrej at certik.cz Sun Mar 23 20:01:44 2008 From: ondrej at certik.cz (Ondrej Certik) Date: Sun, 23 Mar 2008 20:01:44 +0100 Subject: [Doc-SIG] sphinx bug Message-ID: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> 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. 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 From g.brandl at gmx.net Sun Mar 23 20:36:12 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sun, 23 Mar 2008 20:36:12 +0100 Subject: [Doc-SIG] sphinx bug In-Reply-To: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> References: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> Message-ID: 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. > 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. From ondrej at certik.cz Sun Mar 23 21:07:02 2008 From: ondrej at certik.cz (Ondrej Certik) Date: Sun, 23 Mar 2008 21:07:02 +0100 Subject: [Doc-SIG] sphinx bug In-Reply-To: References: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> Message-ID: <85b5c3130803231307m4970491exc3da06c4c1b82df8@mail.gmail.com> > > 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. > > 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 From g.brandl at gmx.net Sun Mar 23 22:13:55 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sun, 23 Mar 2008 22:13:55 +0100 Subject: [Doc-SIG] sphinx bug In-Reply-To: <85b5c3130803231307m4970491exc3da06c4c1b82df8@mail.gmail.com> References: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> <85b5c3130803231307m4970491exc3da06c4c1b82df8@mail.gmail.com> Message-ID: 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. >> > 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. From ondrej at certik.cz Mon Mar 24 02:38:55 2008 From: ondrej at certik.cz (Ondrej Certik) Date: Mon, 24 Mar 2008 02:38:55 +0100 Subject: [Doc-SIG] sphinx bug In-Reply-To: References: <85b5c3130803231201t7098faf1tccc496cefe5cdba@mail.gmail.com> <85b5c3130803231307m4970491exc3da06c4c1b82df8@mail.gmail.com> Message-ID: <85b5c3130803231838n3eca8daak53cf8ea1e7d0d001@mail.gmail.com> On Sun, Mar 23, 2008 at 10:13 PM, Georg Brandl 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