[Docstring-develop] RE: [Doc-SIG] Producing output

[Tony J I. (Tibs) <to...@ls...>]

David Goodger replied to Ueli Schläpfer:
> > - `dps2html` wants an `Errorist` class, whoch I found nowhere and
> >   assumed that David's `Reporter` would do fine.
>
> You're the victim of rapid change. I just checked this change
> in yesterday; `Reporter` is the new name. Tony hasn't had a
> chance to update his code yet.

Well, actually I changed it, but I hadn't announced it.

> What is `dps2html`? I haven't seen that one. Perhaps an old copy?

I think he's just using it as a generic term. Certainly the diffs are
with respect to an old version of pydps/html.py.

Anyway, a status report on this for Doc-SIG might not be a bad thing...

I've been working on a package to read Python modules/packages and
produce HTML therefrom. It uses Tools/compilers and dps/reST to do the
hard work. It is in a *very* alpha stage (it doesn't render lots of
things as HTML, just outputs tags in red for them, for instance, and it
definitely doesn't know everything it should about the Python code yet -
especially, it doesn't check the presence or value of ``__docformat__``,
which is naughty of it! Oh, and it has a very garish colour scheme for
the HTML(!)).

Copies are periodically uploaded as:

	http://www.tibsnjoan.co.uk/reST/pydps.tgz

but see the DPS/reST "table of links" on

	http://www.tibsnjoan.co.uk/

for a reliable pointer, as a name change is possible in the reasonably
near future (it may be becoming "pysource").

The latest version (yesterday's) does indeed now know about Reporter
rather than Errorist. Despite being aimed at Python code, it can process
a text DPS file - for instance::

    python pydps/pydps.py --text textfile.rst textfile.html

(for those following these things, significant changes are that the
command line interface now uses getopt (yuck), and I think I've now got
it representing all expression nodes, so it should be able to cope with
any function arguments that get thrown at it.)

If you're trying to learn about what DPS/reST *does*, then the command::

    python pydps/pydps.py --text textfile.rtxt

produces rather nice output (although "quicktest.py" can produce the
same), and if you want to add in the structure of the (current) Python
information (subject to vast change at zero notice, though - I'm afraid
on a project like this, the ability to refactor (gosh, I used to just
call that "change"!) Python code quickly and safely is very useful),
try::

    python pydps/pydps.py --pretty pythonfile.py

There's zero documentation (well, there's a bit if you run it on
itself!) other than the ``--help`` command. It requires one to have
installed the latest versions of dps and restructuredtext, and the
Tools/compiler for your Python (trying to use the wrong one may lead to
odd effects) - all neat things to have around anyway (!). It is not
expected to work on Python before 2.0.

> > In pydps/html.py, there are several references to `element.tagName`
> > which should probably read `element.tagname`.
>
> You must be looking at an old version. Tony's latest has been
> updated to this particular change.

Yes, days ago (maybe even a week or more).

> If you're interested (and I hope you are!),

I'll second that - the more people playing (and *using* counts as
playing for this game!) the better.

Note that I've been announcing significant changes in pydps over on the
docstring-develop list:

	http://lists.sourceforge.net/lists/listinfo/docstring-develop

rather than on the main Doc-SIG (when I remember), partly because the
changes are too frequent (and unfortunately I'm not integrated with the
CVS tree).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)