From hniksic at gmail.com  Sun Oct 21 11:30:17 2007
From: hniksic at gmail.com (=?ISO-8859-2?Q?Hrvoje_Nik=B9i=E6?=)
Date: Sun, 21 Oct 2007 11:30:17 +0200
Subject: [Doc-SIG] Unindented blocks in reStructuredText
Message-ID: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>

I'd like my rst documents to include snippets of Python that are
pasteable into the interpreter.  Something like:

This text demonstrates creation of a class::

class Foo(object):
    pass

Unfortunately, rst2html warns about "Literal block expected; none
found" and doesn't create a literal block.

If I indent the Python block by any amount of spaces, everything works
-- but then I can no longer paste the example into Python.  Of course,
I can generate the HTML, and paste the code from the browser into
Python, but that makes it much harder to debug Python examples while
writing the documentation.

Am I missing an option here?  I find it surprising that a tool written in
and for Python would make it hard to include valid Python code.  To
clarify my expectations, I'd expect something (approximately) like
this to work:

This text demonstrates creation of a class::

class Foo(object):
    pass
..

(The ".." could mark the end of the block.)

From gael.varoquaux at normalesup.org  Sun Oct 21 11:32:26 2007
From: gael.varoquaux at normalesup.org (Gael Varoquaux)
Date: Sun, 21 Oct 2007 11:32:26 +0200
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
Message-ID: <20071021093226.GB18706@clipper.ens.fr>

On Sun, Oct 21, 2007 at 11:30:17AM +0200, Hrvoje Nik?i? wrote:
> If I indent the Python block by any amount of spaces, everything works
> -- but then I can no longer paste the example into Python. 

You can use a trick in the Python interpreter:

if True:
<paste your code here>


HTH,

Ga?l

From skip at pobox.com  Sun Oct 21 13:11:12 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 21 Oct 2007 06:11:12 -0500
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <20071021093226.GB18706@clipper.ens.fr>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
	<20071021093226.GB18706@clipper.ens.fr>
Message-ID: <18203.13264.394455.780250@montanaro.dyndns.org>


    Gael> You can use a trick in the Python interpreter:

    Gael> if True:
    Gael> <paste your code here>

Note though that copying and pasting that code will give problems if the
pasted code contains any blank lines.

Skip

From goodger at python.org  Sun Oct 21 15:43:13 2007
From: goodger at python.org (David Goodger)
Date: Sun, 21 Oct 2007 09:43:13 -0400
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <18203.13264.394455.780250@montanaro.dyndns.org>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>	<20071021093226.GB18706@clipper.ens.fr>
	<18203.13264.394455.780250@montanaro.dyndns.org>
Message-ID: <471B5771.1010708@python.org>

[skip at pobox.com]
>     Gael> You can use a trick in the Python interpreter:
> 
>     Gael> if True:
>     Gael> <paste your code here>
> 
> Note though that copying and pasting that code will give problems if the
> pasted code contains any blank lines.

How so?

-- 
David Goodger <http://python.net/~goodger>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/doc-sig/attachments/20071021/bf6b5e0e/attachment.pgp 

From goodger at python.org  Sun Oct 21 15:55:07 2007
From: goodger at python.org (David Goodger)
Date: Sun, 21 Oct 2007 09:55:07 -0400
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
Message-ID: <471B5A3B.70905@python.org>

[Hrvoje Nik?i?]
> I'd like my rst documents to include snippets of Python that are
> pasteable into the interpreter.
...
> Am I missing an option here?

You can use

    .. include:: source.py
       :literal:

combined with the :start-after: and :end-before: options.

> I find it surprising that a tool written in and for Python

reST is written in Python but is not specifically for Python.  It's a
general-purpose tool.  (Doctest blocks are an exception to the rule; call them a
wart if you like, an early mistake.)

> would make it hard to include valid Python code.  To
> clarify my expectations, I'd expect something (approximately) like
> this to work:
> 
> This text demonstrates creation of a class::
> 
> class Foo(object):
>     pass
> ..
> 
> (The ".." could mark the end of the block.)

It's an interesting idea, worth considering.  It isn't currently implemented though.

-- 
David Goodger <http://python.net/~goodger>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/doc-sig/attachments/20071021/144a7748/attachment.pgp 

From g.brandl at gmx.net  Sun Oct 21 16:12:47 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Sun, 21 Oct 2007 16:12:47 +0200
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <471B5771.1010708@python.org>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>	<20071021093226.GB18706@clipper.ens.fr>	<18203.13264.394455.780250@montanaro.dyndns.org>
	<471B5771.1010708@python.org>
Message-ID: <fffmp2$hn2$1@ger.gmane.org>

David Goodger schrieb:
> [skip at pobox.com]
>>     Gael> You can use a trick in the Python interpreter:
>> 
>>     Gael> if True:
>>     Gael> <paste your code here>
>> 
>> Note though that copying and pasting that code will give problems if the
>> pasted code contains any blank lines.
> 
> How so?

I think he's referring to the interactive interpreter, where a blank line
will terminate previous indented blocks.

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 skip at pobox.com  Mon Oct 22 03:31:53 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 21 Oct 2007 20:31:53 -0500
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <471B5771.1010708@python.org>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
	<20071021093226.GB18706@clipper.ens.fr>
	<18203.13264.394455.780250@montanaro.dyndns.org>
	<471B5771.1010708@python.org>
Message-ID: <18203.64905.562420.259066@montanaro.dyndns.org>


    Gael> You can use a trick in the Python interpreter:
    >> 
    Gael> if True:
    Gael> <paste your code here>
    >> 
    >> Note though that copying and pasting that code will give problems if
    >> the pasted code contains any blank lines.

    David> How so?

Copy and paste this into the interpreter:

if True:
  x = 1

  y = 10

The solution is to use # where you really want a blank line:

if True:
  x = 1
  #
  y = 10

Skip

From jmg3000 at gmail.com  Mon Oct 22 04:04:12 2007
From: jmg3000 at gmail.com (John Gabriele)
Date: Sun, 21 Oct 2007 22:04:12 -0400
Subject: [Doc-SIG] Unindented blocks in reStructuredText
In-Reply-To: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
References: <8ec1eed60710210230y1ed8c365u7619bb2f4b4713e2@mail.gmail.com>
Message-ID: <65e0bb520710211904n29817960ua1bbd765fc8b50ef@mail.gmail.com>

On 10/21/07, Hrvoje Nik?i? <hniksic at gmail.com> wrote:
> I'd like my rst documents to include snippets of Python that are
> pasteable into the interpreter.

Seems like this might be something best handled by your editor. That
is, you select some text, then have your editor strip the leading
whitespace, possibly add in comment marks on blank lines (per skip's
reply), and feed it to the interpreter.

---John

From hniksic at gmail.com  Wed Oct 24 10:51:13 2007
From: hniksic at gmail.com (=?ISO-8859-2?Q?Hrvoje_Nik=B9i=E6?=)
Date: Wed, 24 Oct 2007 10:51:13 +0200
Subject: [Doc-SIG] rst2newlatex causes latex errors
Message-ID: <8ec1eed60710240151s109b9442p68096b048ebf4c8e@mail.gmail.com>

After a system upgrade (Ubuntu feisty->gutsy), LaTeX has problems with
files generated by rst2newlatex.  For example:

$ pdflatex a.tex
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
[... a lot of verbose output elided ...]
)) (/usr/share/texmf-texlive/tex/latex/base/ifthen.sty)
(/usr/share/texmf-texlive/tex/latex/hyphenat/hyphenat.sty)

! LaTeX Error: File `picins.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name:

The picins.sty file is not part of the regular tex/latex packages, but
it does come with a huge "tetex-src" package.  If I install tetex-src,
I still get the query, but then I can at least enter the full file
name at the prompt, which gets me the correct output.  However, the
tetex-src package claims that it shouldn't be necessary for the proper
operation of LaTeX.

None of this occurs with rst2latex.  Is this rst2newlatex doing
something wrong, or is my LaTeX installation malfunctioning?  Has
anyone else seen this?

On a related note, what is the difference between rst2latex and
rst2newlatex?  I noticed that the latter supports UTF8 text (or simply
defaults to UTF8 encoding) and provides nicer headlines, but it's not
otherwise obvious if it's production quality or just a test -- I can't
find any documentation on it.

From skip at pobox.com  Sat Oct 27 06:45:04 2007
From: skip at pobox.com (skip at pobox.com)
Date: Fri, 26 Oct 2007 23:45:04 -0500
Subject: [Doc-SIG] resurrected modindex
Message-ID: <18210.49744.191842.622583@montanaro.dyndns.org>

A long time ago I wrote a redirector to note and display the most frequently
requested modules from the library reference manual's global module index.
When Georg Brandl did his massive rewrite of the Python manuals that broke.
I finally took the time this evening to resurrect that function.  The result
is here:

    http://www.webfast.com/modindex/

I reset all the counters and seeded the cache with a few modules.  Click
around in the index a few times then reload the above page.  You'll get the
idea.

Skip


From skip at pobox.com  Sat Oct 27 20:21:27 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sat, 27 Oct 2007 13:21:27 -0500
Subject: [Doc-SIG] [Python-Dev] resurrected modindex
In-Reply-To: <ca471dc20710270934p4dde3b24p6ecc9771d197bbc7@mail.gmail.com>
References: <18210.49744.191842.622583@montanaro.dyndns.org>
	<ca471dc20710270934p4dde3b24p6ecc9771d197bbc7@mail.gmail.com>
Message-ID: <18211.33191.801112.652937@montanaro.dyndns.org>

>>>>> "Guido" == Guido van Rossum <guido at python.org> writes:

    Guido> Cool! Is it just a matter of checking this in and it will work on
    Guido> the site?

Alas, no.  I wrote this awhile ago when the site was built w/ ht2html.  My
thing is a simple front-end using Myghty.  As Georg indicated in his
response he has some dynamic stuff in Sphinx which will do this and more.  I
suspect once he goes fully dynamic my little hack won't be necessary any
longer, but I missed it, especially with the new layout where less of the
index is visible without paging down.

I got tired of my modindex URL doing the work necessary to process the index
(and thus being a little slower than just going straight to the index
itself) but not seeing the proper anchors in the file which allowed it to
insert the table and rewrite URLs to allow counting clicks.

Skip