docutils-develop

[Docutils-develop] Putting docutils into Zope 2.5.1

[<pf...@ar...>]

Hi,

I would like to put docutils into my Zope.  
Has anybody already done this?
Or can someone give me some hints and pointers, where to start?

Especially I would like to use ReStructuredText together with CMF and CMFWiki.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[David G. <go...@us...>]

Peter Funk wrote:
> I would like to put docutils into my Zope.
> Has anybody already done this?

Looks like nobody else has answered yet, so I'll give the obvious
answer: not that I know of.

> Or can someone give me some hints and pointers, where to start?

I'll be happy to help, but I know nothing about Zope.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[Richard J. <rj...@ek...>]

On Tue, 13 Aug 2002 6:26 pm, Peter Funk wrote:
> I would like to put docutils into my Zope.
> Has anybody already done this?
> Or can someone give me some hints and pointers, where to start?

Sure, start with the stuff I just threw into the sandbox. Needed something to 
break the monotony of the day job ;)

Anyway, it works, mostly. It doesn't:

1. have any control over options
2. have any capturing of Reporter output

.. because I spent the better part of an hour trying to figure how I could 
sanely control both, and gave up ;)


    Richard

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[Richard J. <rj...@ek...>]

On Wed, 14 Aug 2002 3:18 pm, Richard Jones wrote:
> On Tue, 13 Aug 2002 6:26 pm, Peter Funk wrote:
> > I would like to put docutils into my Zope.
> > Has anybody already done this?
> > Or can someone give me some hints and pointers, where to start?
>
> Sure, start with the stuff I just threw into the sandbox. Needed something
> to break the monotony of the day job ;)
>
> Anyway, it works, mostly. It doesn't:
>
> 1. have any control over options
> 2. have any capturing of Reporter output
>
> .. because I spent the better part of an hour trying to figure how I could
> sanely control both, and gave up ;)

Oh, if anyone wants to play with it:

1. I've already hooked in PropertyManager to prepare for the options, and
2. The "here" code at the top of the __init__.py will figure the product's
   installed directory, so you can find a config file. I don't believe it's
   necessary any more.

There's probably some way of faking an options object, but I just couldn't get 
it to fly...

The Reporter stuff seemed far too hard-coded for my brain to cope with at 
present :)  [I delved down into the readers code, and tried hacking together 
my own publisher, but I need to do some paying work :)]


    Richard

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[David G. <go...@us...>]

Re http://docutils.sf.net/sandbox/richard/ZReST/, Richard Jones wrote:
> Anyway, it works, mostly. It doesn't:
> 
> 1. have any control over options
> 2. have any capturing of Reporter output
> 
> .. because I spent the better part of an hour trying to figure how I
> could sanely control both, and gave up ;)

Can you give us specifics, of what you want to do?  Control options
how?  Capture Reporter output how?

> There's probably some way of faking an options object, but I just
> couldn't get it to fly...

Why fake it?  Isn't it easy to get a real one?

> The Reporter stuff seemed far too hard-coded for my brain to cope
> with at present :)

Are you trying to capture the stderr output of Reporter, or the
<system_message> elements it produces?  Why?

Anyhow, I appreciate the effort.  You're exercising Docutils in a way
it hasn't been exercised before, which brings out deficiencies.  Like
when you try to use muscles you don't ordinarily use, they hurt the
next day.  I see some places where the code is biased towards files
and paths, which should be fixed.  It should be easier to say, "Here's
a reStructuredText string; give me HTML."

Some comments on ZReST.render::

    def render(self):
        ''' Render the source to HTML
        '''
        # format with strings
        pub = core.Publisher()
        pub.set_reader('standalone', None, 'restructuredtext')
        pub.set_writer('html')

        # go with the defaults
        pub.set_options()

        # this is needed, but doesn't seem to do anything
        pub.options._destination = ''

It's currently needed to calculate relative paths for the stylesheet
link.  But you shouldn't have to deal with it.  It's one of the
file-biased things I mentioned that needs fixing.

        # input
        pub.source = io.StringInput(pub.options)
        pub.source.source = self.source

        # output - not that it's needed
        pub.destination = io.StringOutput(pub.options)

If it's not needed, use ``io.NullOutput``.  You can access the data
from ``pub.writer.astext()`` (produces Unicode).  But further down, I
see that you *do* need the ``StringOutput`` object; it does the output
encoding (default UTF-8).

        # parse!
        document = pub.reader.read(pub.source, pub.parser, pub.options)

        # do the format
        self.formatted = pub.writer.write(document, pub.destination)

Instead of these, you can just use::

    self.formatted = pub.publish()

BTW, I like the name.  We all need more Z-rest.  (If you don't get it,
you're probably American.  "Zee" indeed! ;-)

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[Richard J. <rj...@ek...>]

On Thu, 15 Aug 2002 10:54 am, David Goodger wrote:
> Re http://docutils.sf.net/sandbox/richard/ZReST/, Richard Jones wrote:
> > Anyway, it works, mostly. It doesn't:
> >
> > 1. have any control over options
> > 2. have any capturing of Reporter output
> >
> > .. because I spent the better part of an hour trying to figure how I
> > could sanely control both, and gave up ;)
>
> Can you give us specifics, of what you want to do?  Control options
> how?  Capture Reporter output how?

One of the big issues is that I'm not sure what all the options are :)

Stylesheet location and Reporter verbosity are two biggies at the moment. I'd 
want to capture the Reporter output to display on the Zope edit page, rather 
than it just going to stdout/err ;)


> > There's probably some way of faking an options object, but I just
> > couldn't get it to fly...
>
> Why fake it?  Isn't it easy to get a real one?

I couldn't find a mechanism to do so - I poked around the code and docs for 
quite some time, but nothing was immediately obvious. The docs don't seem to 
have much at all regarding the "API".


> > The Reporter stuff seemed far too hard-coded for my brain to cope
> > with at present :)
>
> Are you trying to capture the stderr output of Reporter, or the
> <system_message> elements it produces?  Why?

I'd want to get the actual message elements, so I can display them sensibly as 
I described above.


> Some comments on ZReST.render::
> [snip]
> Instead of these, you can just use::
>
>     self.formatted = pub.publish()

I did that, initially, but then I unpacked it so I could try manipulating the 
options and reporting.

Another improvement that I've just thought of is to extract the title from the 
DOM and set it as the object's "title" attribute (which is used by Zope for 
various things).


> BTW, I like the name.  We all need more Z-rest.  (If you don't get it,
> you're probably American.  "Zee" indeed! ;-)

:)

I'm like, sooo not American :)


    Richard (aka Bruce)

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[David G. <go...@us...>]

Richard Jones wrote:
> One of the big issues is that I'm not sure what all the options are :)

Have you read http://docutils.sf.net/docs/tools.html yet?  It's up to date.

> Stylesheet location and Reporter verbosity are two biggies at the moment.

``options.stylesheet``, ``options.report_level``, and
``options.halt_level``.

> I'd want to capture the Reporter output to display on the Zope edit page,
> rather than it just going to stdout/err ;)

It would be easy to capture the stderr stream::

    sys.stderr = my_stream_object

Reading ahead though, I guess that's not what you're after.

>>> There's probably some way of faking an options object, but I just
>>> couldn't get it to fly...
>> 
>> Why fake it?  Isn't it easy to get a real one?
> 
> I couldn't find a mechanism to do so - I poked around the code and docs for
> quite some time, but nothing was immediately obvious.

You seem to have found it though.  ``docutils.core.Publisher.set_options``
returns an options object with default values.

> The docs don't seem to have much at all regarding the "API".

True.  It's on the list.  But I think most Docutils API docs will remain in
the docstrings for the time being.  The API itself is not mature enough to
fix the API in external docs yet.

It will help once PySource or equivalent is complete and part of Docutils
proper; API docs will be auto-generated from docstrings, mostly.  That is my
intended focus over the next few weeks.

>>> The Reporter stuff seemed far too hard-coded for my brain to cope
>>> with at present :)
>> 
>> Are you trying to capture the stderr output of Reporter, or the
>> <system_message> elements it produces?  Why?
> 
> I'd want to get the actual message elements, so I can display them sensibly as
> I described above.

The <system_message> elements are inserted into the document tree, adjacent
to the problems themselves where possible.  Some (those generated
post-parse) are kept until later, in ``document.messages``, and added as a
special final section, "Docutils System Messages".

Would you want these messages *not* to be in the document?  Or would a list
of references be enough?  Docutils could be made to generate hyperlinks to
all known system_messages and add them to the document.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Putting docutils into Zope 2.5.1

[Richard J. <rj...@ek...>]

On Thu, 15 Aug 2002 11:37 am, David Goodger wrote:
> Richard Jones wrote:
> > One of the big issues is that I'm not sure what all the options are :)
>
> Have you read http://docutils.sf.net/docs/tools.html yet?  It's up to date.

It has the stuff I need, thanks.


> >>> There's probably some way of faking an options object, but I just
> >>> couldn't get it to fly...
> >>
> >> Why fake it?  Isn't it easy to get a real one?
> >
> > I couldn't find a mechanism to do so - I poked around the code and docs
> > for quite some time, but nothing was immediately obvious.
>
> You seem to have found it though.  ``docutils.core.Publisher.set_options``
> returns an options object with default values.

Yeah, that was the result of my poking around :)


> >>> The Reporter stuff seemed far too hard-coded for my brain to cope
> >>> with at present :)
> >>
> >> Are you trying to capture the stderr output of Reporter, or the
> >> <system_message> elements it produces?  Why?
> >
> > I'd want to get the actual message elements, so I can display them
> > sensibly as I described above.
>
> The <system_message> elements are inserted into the document tree, adjacent
> to the problems themselves where possible.  Some (those generated
> post-parse) are kept until later, in ``document.messages``, and added as a
> special final section, "Docutils System Messages".
>
> Would you want these messages *not* to be in the document?  Or would a list
> of references be enough?  Docutils could be made to generate hyperlinks to
> all known system_messages and add them to the document.

I'd rather that the messages be both in the document, and available to the 
edit page. There's a screen cap of the edit page in my sandbox, just so you 
know what I'm on about :) The reporter's messages would be displayed above
the edit box, with the really serious stuff in red. When I get around to
implementing an FTP interface, the messages will be prepended to the
downloaded file with some marker, and stripped out on upload.

Screenshot: http://docutils.sf.net/sandbox/richard/ZReST/snapshot4.png


   Richard