parsed-literal problems
Andrea Crotti
This block of code for example is recognised and colored perfectly:
.. parsed-literal::
import warnings
class SomeClass(object):
def run_script(self, script, context):
warnings.warn(("'run_script' will be replaced in next
version"),
DeprecationWarning)
print 'doing something'
return self.run(script, context)
def run(self, script, context=None):
pass
while this isn't
.. parsed-literal::
try:
prog = open(filename, "rU").read()
prog = prog.strip() + '\n'
except IOError, err:
I thought it was just an highlighting problem, but it's just not seen
as a parsed-literal.
What can I be missing?
They have both one newline at beginning and end, what can be the problem?
Guenter Milde
> I'm fighting a little bit in trying to understand parsed-literal.
...
> This block of code for example is recognised and colored perfectly:
...
> I thought it was just an highlighting problem, but it's just not seen
> as a parsed-literal.
What does the output look like? Is there an error message?
Does a blank line between the directive start line and the content block help?
Try to create a minimal working example: copy the "failing" block to a new
document. Remove stepwise content and try which line/part changes the
behaviour.
> What can I be missing?
Parsed literal is parsed as *reStructuredTeXt*. See
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block
Günter
Andrea Crotti
> What does the output look like? Is there an error message? Does a
> blank line between the directive start line and the content block
> help? Try to create a minimal working example: copy the "failing"
> block to a new document. Remove stepwise content and try which
> line/part changes the behaviour.
It was quite simple, this is a simple failing example:
.. parsed-literal::
class SampleCommand(AbstractCommand):
def do(self):
# var
(and I don't get any compilation warnings).
I guess sphinx thinks that this code is not valid python (even if it is),
and so it doesn't bother.
But I didn't think it was doing such a check, and how do I stop it
checking this?
Andrea Crotti
>
> It was quite simple, this is a simple failing example:
> .. parsed-literal::
> class SampleCommand(AbstractCommand):
> def do(self):
> # var
>
>
Uhm I thought that with code-block or at least "highlight" I could get some
results but it's the same, it's not recognizes as python code...
(tried with both)
.. highlight:: python
...
.. code-block:: python
Andrea Crotti
>
> .. parsed-literal::
> class SampleCommand(AbstractCommand):
> def do(self):
> # var
>
>
> (and I don't get any compilation warnings).
> I guess sphinx thinks that this code is not valid python (even if it is),
> and so it doesn't bother.
>
> But I didn't think it was doing such a check, and how do I stop it
> checking this?
So should I file a bug report about this or it's supposed to work in
this way?
Guenter Milde
> On 10/27/2011 01:54 PM, Andrea Crotti wrote:
>> It was quite simple, this is a simple failing example:
>> .. parsed-literal::
>> class SampleCommand(AbstractCommand):
>> def do(self):
>> # var
>> (and I don't get any compilation warnings).
What do you expect and what do you get?
> So should I file a bug report about this or it's supposed to work in
> this way?
I think so, but cannot tell without a clear statement of the expected and
actual output.
Mind, that "parsed-literal" does not imply syntax highlight, but instead
accepts reStructuredText elements like links and inline markup.
Günter
Andrea Crotti
> What do you expect and what do you get?
I would think to get the code highlighted, instead is just not
recognized as code,
and that also if I use highlight or code-block...
I filled a bug for it:
https://bitbucket.org/birkenfeld/sphinx/issue/806/highlight-parsed-literal-not-working-for
Guenter Milde
> On 10/28/2011 10:28 PM, Guenter Milde wrote:
>> What do you expect and what do you get?
> I would think to get the code highlighted, instead is just not
> recognized as code,
I am not sure "parsed-literal" content should be highlit as code. (But, of
course a consistent behaviour is to be expected - i.e. either always or
never highlight parsed-literal as code.)
> and that also if I use highlight or code-block...
The "highlight" directive is *not* intended to highlight content, instead:
The highlighting language can be changed using the highlight directive,
used as follows::
.. highlight:: c
This language is used until the next highlight directive is encountered.
-- http://sphinx.pocoo.org/markup/code.html
Highlighting is expected only with a standard (non-parsed) literal block
or a code-block directive::
# this should be considered Python code (in Sphinx) unless the
# "highlight language" is changed.
.. code-block:: C
/* this directive content should be C code */
> I filled a bug for it:
> https://bitbucket.org/birkenfeld/sphinx/issue/806/highlight-parsed-literal-not-working-for
I leave this to the Sphinx developers...
Günter
Georg Brandl
Hash: SHA1
On 10/29/2011 01:19 PM, Guenter Milde wrote:
> On 2011-10-29, Andrea Crotti wrote:
>> On 10/28/2011 10:28 PM, Guenter Milde wrote:
>>> What do you expect and what do you get?
>
>
>> I would think to get the code highlighted, instead is just not recognized
>> as code,
>
> I am not sure "parsed-literal" content should be highlit as code. (But, of
> course a consistent behaviour is to be expected - i.e. either always or
> never highlight parsed-literal as code.)
Hi G�nter,
you are of course right. If I had my way, I wouldn't highlight anything in
parsed-literal blocks. But the problem is that I found no way to distinguish
between normal literal blocks and parsed literal blocks that have only "plain"
(i.e. nothing that was parsed) text inside...
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.18 (GNU/Linux)
iEYEARECAAYFAk6vpHMACgkQN9GcIYhpnLBgeQCcDaMBi5L8cm5kUJpefrrZriRH
TH0AoJta8i/eLvoys6962qggXmBgd0wv
=QOzI
-----END PGP SIGNATURE-----
Guenter Milde
> On 10/29/2011 01:19 PM, Guenter Milde wrote:
...
>> I am not sure "parsed-literal" content should be highlit as code.
>> (But, of course a consistent behaviour is to be expected - i.e. either
>> always or never highlight parsed-literal as code.)
...
> you are of course right. If I had my way, I wouldn't highlight
> anything in parsed-literal blocks. But the problem is that I found no
> way to distinguish between normal literal blocks and parsed literal
> blocks that have only "plain" (i.e. nothing that was parsed) text
> inside...
I remember the same problem when introducing code-highlighting via the
"listings" package in the Docutils latex writer. The answer I got back then
was: "There is no need for this distinction in the standard
Docutils."
I see two ways out here:
a) Convince David that it makes sense to keep a tag of the "origin" of a
literal_block doctree node. This could be either a class argument, or a
"hidden attribute" as part of the "lossless rst parser" (pre-requisite to
write back parsed documents as rst without loss of information).
b) Accept, sanitize and document the behaviour of "parsed-literal" in Sphinx.
Acutally, the documentation of the directive,
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block
says:
Parsed literal blocks are useful for adding hyperlinks to code examples.
Things to consider/document:
* parsing order: [rst, code-highlight] vs. [code-highlight, rst]
* How to represent and lay out e.g. a link that is a keyword, part of
a string or comment?
* Precedence for other inline markup vs. syntax highlight.
For Docutils, I rather plan to go way a). The idea is to have a configurable
"default-literal-block" directive (similar to "default-role") that maps the
"::" syntax to, e.g., "literal", "parsed-literal", or "code".
Günter