[Docstring-develop] pydps futures (was RE: Document titles)

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

I started this to reply to Ueli, and then realised that my response was
essentially just:

    I think that David's approach (as I understand it)
    of providing optional methods to produce the effect
    wanted is probably the best way forward.

but that I wanted to diverge sideways...

I'm aiming to refactor pydps (bouncy fun - and maybe produce pysource
out of it, who knows) to follow David's Reader/Transformer/Writer model
in the next week or so (I've not got very far yet, though, apart from
thinking about it lots).

I *actually* expect to have a flowline that's something like (sorry, no
ASCII art):

1. Reader

   - uses compiler [1]_ to extract information
     from the Python source code
   - calls the reST parser on any docstrings
     that need it
   - combs_ any of the resultant docstrings

2. Transformer

   - (actually, the last two steps from the Reader
     might arguably go here - we need to do the
     docstring parsing after we *know* we've found
     any ``__docformat__`` value, after all)
   - produces a DPS tree from the Python information
   - combs_ it as required [2]_

3. Writer

   - outputs the DPS tree as (in the first instance)
     HTML


Since the HTML Writer would be handling a pure DPS tree, it would then
be a good candidate for moving out of pysource into the main docutils
tree (if we have one by then). I rather hope that at least the
FootnoteComb would also be such a candidate.

Combs
-----
The metaphor of combing through hair to remove tangles is a bit iffy,
but I like the term (I think David calls them Filters, which is less
obvious to me). I'm expecting to have a series of combs which can be run
on a DPS tree or subtree. Obvious ones are:

TitleComb
  This does what David wants to produce a title.
  I suspect that it raises an exception if it
  can't do so, at which point it is up to the
  caller to do something sensible (either ignore
  the problem, or provide a default title).

FootenoteComb
  This runs over a subtree (clearly for Python code,
  we don't want to run it over anything bigger than
  a docstring, lest we confuse footnotes!) and sorts
  out the numbering (in my development version of
  pyspd (not on the web yet) this is actually done
  as part of the HTML output phase, which is clearly
  the Wrong Place for it.

  David - a question or two on this. Each autonumbered
  footnote/footnote reference has the attribute 'auto'
  set to "1". I want to *insert* actual footnote numbers
  into the tree. I can just add a new attribute 'auto-number'
  into elements as required, *or* I could ask that you set
  'auto' to be "-1" for the "no number yet" case, and use
  'auto' to store the *actual* number calculated. Which to
  do is a style issue, so I'd prefer to leave it up to you
  (but using the same attribute would make things a bit
  neater in the code - I'm not sure if it would generate
  as elegant XML, though - I'd need to look up the detailed
  attribute present/absent rules).

ContentsComb
  This runs over the entire tree, and locates <section>
  elements. It produces a <contents> subtree, which can
  be inserted at the appropriate place, with links to
  the <section>s. It needs to make sure that the links
  it uses are *real*, so ideally it will use the "implicit"
  link for a section when it exists, and it will have to
  invent one when the implicit link isn't there (presumably
  because the section is the twelfth "Introduction" in the
  document...).

LinksComb
  This handles the indirect hyperlinks. It probably comes
  in two phases, because in a Python context we need to
  *resolve* them on a per-docstring basis, but if the
  user is trying to do the callout form of presentation,
  they would then want to group them all at the end of the
  document.


.. [1] I note that in the CVS for Python, the compiler module
   is now in the standard library - hurrah! And it also looks
   like the bug that stopped the 1.2aX compiler module from
   *working* has also been fixed (just as I was about to find
   out how to submit a bug report - even more hurrah!)

.. [2] does that count as verbing a noun?

Tibs

(So much to do, so little etc. And I've just been given news that I'm to
start on a *really exciting* project for paid work, as well.)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)