Unindented blocks in reStructuredText

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

Unindented blocks in reStructuredText

Hrvoje Nikšić-3
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.)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Unindented blocks in reStructuredText

Gael Varoquaux
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Unindented blocks in reStructuredText

Skip Montanaro-3

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

Re: Unindented blocks in reStructuredText

David Goodger
[[hidden email]]
>     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>


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

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Unindented blocks in reStructuredText

David Goodger
In reply to this post by Hrvoje Nikšić-3
[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>


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

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Unindented blocks in reStructuredText

Georg Brandl-2
In reply to this post by David Goodger
David Goodger schrieb:

> [[hidden email]]
>>     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.

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

Re: Unindented blocks in reStructuredText

Skip Montanaro-3
In reply to this post by David Goodger

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

Re: Unindented blocks in reStructuredText

John Gabriele
In reply to this post by Hrvoje Nikšić-3
On 10/21/07, Hrvoje Nikšić <[hidden email]> 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig