Docutils: Documentation Utilities

On Thu, Oct 17, 2002, Aahz wrote:
>
> Given the full path /users/aahz/book/chapter/source.txt, in the context
> of processing a directive in source.txt, how do I retrieve the value
> /users/aahz/book/chapter/ ?
> 
> I'd have thought state_machine.document.source would have the path (or
> at least a FileInput object from which it could be retrieved), but it
> doesn't.

I finally found it in state_machine.document.current_source.  I consider
this far from obvious.
-- 
Aahz (aahz@...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Aahz wrote:
> Given the full path /users/aahz/book/chapter/source.txt, in the
> context of processing a directive in source.txt, how do I retrieve
> the value /users/aahz/book/chapter/ ?
> 
> I'd have thought state_machine.document.source would have the path
> (or at least a FileInput object from which it could be retrieved),
> but it doesn't.

``state.document['source']`` has the path of the first source,
relative to the current directory.  I'd recommend you use
``state.document.current_source`` though, since the source may change
with an "include" directive.  To get the directory of the current
source, use::

    os.path.dirname(os.path.abspath(state.document.current_source))

Thanks, this showed me that the "include" directive wasn't handling
paths properly.  The path given for the include file should be
interpreted relative to the file it's contained within.  See
docutils/parsers/rst/directives/misc.py, functions "include" and
"raw", for details.

> I finally found it in state_machine.document.current_source.  I consider
> this far from obvious.

You find that an undocumented (except for docstrings) internal
implementation detail is not obvious?  Good for you.

-- 
David Goodger  <goodger@...>  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/

On Fri, Oct 18, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Given the full path /users/aahz/book/chapter/source.txt, in the
>> context of processing a directive in source.txt, how do I retrieve
>> the value /users/aahz/book/chapter/ ?
>> 
>> I'd have thought state_machine.document.source would have the path
>> (or at least a FileInput object from which it could be retrieved),
>> but it doesn't.
> 
> ``state.document['source']`` has the path of the first source,
> relative to the current directory.  I'd recommend you use
> ``state.document.current_source`` though, since the source may change
> with an "include" directive.  To get the directory of the current
> source, use::
> 
>     os.path.dirname(os.path.abspath(state.document.current_source))

Here's what I'm actually doing::

    source = document.current_source
    if source is None:
        return os.getcwd()
    else:
        dirname = os.path.dirname(os.path.abspath(source))
        if dirname is None:
            return os.getcwd()
        else:
            return dirname

>> I finally found it in state_machine.document.current_source.  I consider
>> this far from obvious.
> 
> You find that an undocumented (except for docstrings) internal
> implementation detail is not obvious?  Good for you.

That was just me being a bit grumpy about what I saw as an arbitrary
change of an attribute name (``source`` gets used in a lot of different
places in the code, so I was using that to track things down).  Now that
I understand what's going on, I'm a bit less unhappy, but I think that
perhaps the names should be changed from ``source``/``current_source`` to
``original_source``/``source``.

I'm still a bit confused about the distinction between ``document.source``
(which is ``None``) and ``document['source']``.

I'm also thinking that the use of ``Element.__getitem__`` needs redesign;
I can just imagine what Alex Martelli would say about getting different
kinds of data based on the type of key presented.  Probably the simplest
approach would be to stop using ``__getitem__`` as a proxy for
``Element.attributes``.  (I'm not going to argue with you, but I can
tell you that Alex *WILL* argue with you if/when he sees that. ;-)
-- 
Aahz (aahz@...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Aahz wrote:
> Here's what I'm actually doing::
> 
>     source = document.current_source
>     if source is None:
>         return os.getcwd()

``document.current_source`` will only be set to ``None`` after parsing
is finished.  If this code is inside a directive function, parsing is
ongoing, so you shouldn't need the test.  If that local ``source`` is
ever ``None``, it would be a bug, and the test above would mask it.

> Now that I understand what's going on, I'm a bit less unhappy, but I
> think that perhaps the names should be changed from
> ``source``/``current_source`` to ``original_source``/``source``.

"source" is the source of the element itself.  It doesn't change.
"current_source" is the source of the line of data currently being
parsed.  This may change, for example if an "include" directive is
used.  The names make sense to me.

> I'm still a bit confused about the distinction between
> ``document.source`` (which is ``None``) and ``document['source']``.

``document.source`` is an internal instance attribute, an
implementation detail, added to get better error/warning output.
``document['source']`` is an external attribute.  All external
attributes are stored in ``element.attributes`` (a dict), get
exported as XML attributes, and are documented in spec/docutils.dtd
and spec/doctree.txt.

> I'm also thinking that the use of ``Element.__getitem__`` needs
> redesign; I can just imagine what Alex Martelli would say about
> getting different kinds of data based on the type of key presented.
> Probably the simplest approach would be to stop using
> ``__getitem__`` as a proxy for ``Element.attributes``.  (I'm not
> going to argue with you, but I can tell you that Alex *WILL* argue
> with you if/when he sees that. ;-)

You know what?  I don't care what Alex would say. :-)

The technique makes sense for this application.  ``element[0]`` gives
the first child, and ``element['name']`` gets the "name" attribute.
It may be a wart to some eyes, but it's a very practical and useful
wart that reduces complexity.  If you don't like it, use
``element.children[0]`` and ``element.attributes['name']``; but they
don't do the extra bookkeeping that ``Element.__setitem__`` and
friends do.

I seem to recall a quote about just this topic, maybe it was Guido
expressing his disgust with a similar convention.  But I can't locate
it now.  Pity.

-- 
David Goodger  <goodger@...>  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/