Restructured text parsing not showing h1 levels.

[Michael Lake]

Hi all

I have a problem I think when I use the markup package. This provides markdown,
textile and restructuredtext markups. I have the following in views.py:

def testwiki:

content = '''
Restructured Text Test
======================

How de do.

Sub Heading
-----------

Hi
'''

return render_to_response("app/testwiki.html" , {'content': content})

In testwiki.html I have {{ content|restructuredtext}}

The page is displayed but there is no heading level 1 i.e. I'm missing "Restructured
Text Test". If I place any character above the heading like 'a' then the heading
shows fine. It also works fine if I have a H1 anywhere lower down. But If I just wish
to have one H1 level Im in problems.

Maybe this is a restructured text parsing problem? Has anyone seen this?

Mike
--
Michael Lake

[Malcolm Tredinnick]

This is normal Restructured Text behaviour, although I agree it's a bit
weird when you first see it. It's kind of a consequence of a ReST
feature combined with us (Django) diving into the middle of the output
processing pipeline to extract only what we need.

There is no specific way to specify the document title or subtitle. So
ReST uses the initial *unique* heading markup as the document title. The
restructured text template tag only returns the document "fragment"
after the markup has been performed. This does include the document
title, which is why you are "losing" the first heading.

This is in the ReST documentation
(http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html )
under "Document Structure", if you care.

Not sure what a good workaround would be that is always going to work.

Regards,
Malcolm

[Michael Lake]

Hi

> On Mon, 2007-04-02 at 15:24 +1000, Michael Lake wrote:
>
>>Hi all
>>I have a problem I think when I use the markup package. This provides markdown,
>>textile and restructuredtext markups. I have the following in views.py:
>>
>>def testwiki:
>>
>> content = '''
>>Restructured Text Test
>>======================

....

>>'''
>>
>>return render_to_response("app/testwiki.html" , {'content': content})
>>In testwiki.html I have {{ content|restructuredtext}}
>>
>>The page is displayed but there is no heading level 1 i.e. I'm missing "Restructured
>>Text Test". If I place any character above the heading like 'a' then the heading
>>shows fine. It also works fine if I have a H1 anywhere lower down. But If I just wish
>>to have one H1 level Im in problems.

Malcolm Tredinnick wrote:
> This is normal Restructured Text behaviour, although I agree it's a bit
> weird when you first see it. It's kind of a consequence of a ReST
> feature combined with us (Django) diving into the middle of the output
> processing pipeline to extract only what we need.
>
> There is no specific way to specify the document title or subtitle. So
> ReST uses the initial *unique* heading markup as the document title. The
> restructured text template tag only returns the document "fragment"
> after the markup has been performed. This does include the document
> title, which is why you are "losing" the first heading.
>
> This is in the ReST documentation
> (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html )
> under "Document Structure", if you care.
>
> Not sure what a good workaround would be that is always going to work.

Bugger :-) That will probably wipe it out of use for me.
I'm writing an app where users will be inputting experiment descriptions using a wiki
hence the use of either markdown, textile or ReST. There will only be one H1 level.
Markdown is nice but does not have tables (I have a table extension for
Python-Markdown but it looks comlicated to install), textile uses h1., h2. which I
don't like as much and ReST looked fine.

The users will also be incorporating text entry boxes into the wiki so I have written
a small filter that turns [[name=volts size=40]] into <input name="volts" size=40/>.
It's neat but I wanted the tables to allow users to align the input boxes.

I'll probably have to look at extending Markdown and potter back here and ask
questions when I get stuck.

Thanks Malcolm.

Mike
--
Michael Lake

[James Bennett]

On 4/2/07, Michael Lake <Mike...@uts.edu.au> wrote:
> I'll probably have to look at extending Markdown and potter back here and ask
> questions when I get stuck.

If you want to use ReST, remember that the Django template filter is
not the only way to use it -- you could easily write your own filter
which pulls out the parts of the document you're interested in
(including the title).

--
"Bureaucrat Conrad, you are technically correct -- the best kind of correct."

[Jonathan Buchanan]

I use something like the following instead, the important difference
being that it returns the 'html_body' part instead of the 'fragment'
part. Also, this implementation doesn't check for docutils not being
installed as the django.contrib.markup templatetag does, as I'm doing
the HTML translation at Model save time:

from docutils.core import publish_parts
from django.conf import settings

def restructuredtext(value):
docutils_settings = getattr(settings,
'RESTRUCTUREDTEXT_FILTER_SETTINGS', {})
parts = publish_parts(source=value, writer_name='html4css1',
settings_overrides=docutils_settings)
return parts['html_body']

Regards,
Jonathan.

[Chris Moffitt]

>
> This is normal Restructured Text behaviour, although I agree it's a bit
> weird when you first see it. It's kind of a consequence of a ReST
> feature combined with us (Django) diving into the middle of the output
> processing pipeline to extract only what we need.

Ah yes, it is the "normal behavior" but it can be configured. Take a look
here -
http://docutils.sourceforge.net/docs/user/config.html

and I think you're specifically looking for this text:

"doctitle_xform

Enable or disable the promotion of a lone top-level section title to
document title (and subsequent section title to document subtitle
promotion; docutils.transforms.frontmatter.DocTitle)."

You'll need to make this change in your /etc/docutils.conf file (or in one
of the other files it mentions). Then, it should work for you.

Good luck,
Chris

[doug.na...@gmail.com]

There is an advanced RestructuredText django plugin I wrote with the
help of David Goodger:

https://svn.python.org/conference/django/trunk/pycon/markup/

This worked very very well, and deals with the problem you ran into by
default.
You can also set overrides in the settings file:
class NullStream(object):
'''keep the log empty of ReST warnings'''
def write(*args, **kwdargs): pass
writeline = write
writelines = write

RESTRUCTUREDTEXT_FILTER_SETTINGS = { 'cloak_email_addresses': True,
'file_insertion_enabled': False,
'raw_enabled': False,
'warning_stream': NullStream()}

It includes model a validator
IsValidReST
Two filters:
restructuredtext
restructuredtext_has_errors
And a useful template tag:
Example:
::

{% restructuredtext %}
===================================
To: {{ send_to }}
===================================
{% include "email_form.rst" %}
{% endrestructuredtext %}

Hope that helps!

On Apr 2, 9:12 am, "Chris Moffitt" <c...@moffitts.net> wrote:
> > This is normal Restructured Text behaviour, although I agree it's a bit
> > weird when you first see it. It's kind of a consequence of a ReST
> > feature combined with us (Django) diving into the middle of the output
> > processing pipeline to extract only what we need.
>
> Ah yes, it is the "normal behavior" but it can be configured. Take a look

> here -http://docutils.sourceforge.net/docs/user/config.html

[Michael Lake]

Hi all

Thanks for this help.

doug.na...@gmail.com wrote:
> There is an advanced RestructuredText django plugin I wrote with the
> help of David Goodger:
> https://svn.python.org/conference/django/trunk/pycon/markup/

That code looks useful, thanks. It will take me a while to have a look at it and see
how it work.s

"Chris Moffitt" <c...@moffitts.net> wrote:
>>This is normal Restructured Text behaviour, although I agree it's a bit
>>weird when you first see it. It's kind of a consequence of a ReST
>>feature combined with us (Django) diving into the middle of the output
>>processing pipeline to extract only what we need.
>
>Ah yes, it is the "normal behavior" but it can be configured. Take a look
>here -http://docutils.sourceforge.net/docs/user/config.html
>and I think you're specifically looking for this text:
>"doctitle_xform
>

>You'll need to make this change in your /etc/docutils.conf file (or in one
>of the other files it mentions). Then, it should work for you.

Excellent! I didn't know it was easily configurable. I don't have a
/etc/docutils.conf as docutils is just in the site-packages directory but now knowing
what to look for I can see where this is set. I modified
docutils/readers/standalone.py as set the value from 1 to 0 and now a lone H1 is
shown :-)

It's probably best to use for me to look at trying Dougs code and Jonathan Buchanan's
suggestion rather than modifying the site-package.

Thanks all :-)

--
Michael Lake