Re: [Docutils-users] Approach for resolving unknown references with pure docutils

[Tony N <to...@gi...>]

On September 20, 2017 at 11:19:44 PM, David Goodger (go...@py...)
wrote:

On Wed, Sep 20, 2017 at 9:29 PM, Tony N <to...@gi...> wrote:
> Docutils Users,

This should be on the docutils-develop list.

> Currently, sphinx has an infrastructure geared toward resolving unknown
> references. I have not been able to find an approach for a custom
reference
> resolver mentioned before on the list.
>
> What would the best approach be for wiring in a callback to resolve
missing
> references with pure docutils?

Not exactly sure what you're talking about. Examples go a long way.

I'm guessing you're talking about resolving hyperlink references. (I
don't like to guess; please don't make me.)

So let’s say we have a role that isn't registered *and* is also an unknown
reference, but I have the logic to figure out the role and resolve the
hyperlink if I could catch the role + target. (So pretty much what you
said, and what sphinx does, although they complicate it a lot)

For instance:

:class:`flask:flask.Request` and :class:`django:django.http.HttpRequest`

In this instance, I would hope to be able to catch ‘class’,
‘flask:flask.Request’, and then I can handle resolving it into a reference.

Now I’d get this: <string>:4: (ERROR/3) Unknown interpreted text role
"class"

To be specific, here’s what Sphinx does (I neglected to cite example
earlier since it adds a lot of overhead):

- ReferenceResolver transformer
https://github.com/sphinx-doc/sphinx/blob/6765c54/sphinx/transforms/post_transforms/__init__.py#L63

- Callback that resolves references:
https://github.com/sphinx-doc/sphinx/blob/3f1f5bb/sphinx/ext/intersphinx.py#L270

So to revise the question, it’s also two things:

1. Handle the role that’s unknown (I guess the simplest solution is to
write a pure-docutils class role?) I may end up having to port “domains”
from sphinx to being a pure docutils extension at that rate.

2. Also handle resolving the reference. But note, the role plays a part in
deducing the reference. Which I don’t expect would be a problem, that
information would be there (right?)



> If it’s a transformer, when and where would
> would it be added/applied?

Transforms, not "transformers". Docutils has one Transformer,
docutils.transforms.Transformer, which stores and applies Transforms.

Understood.



> (It appears the other reference resolvers in
> docutils are in the Reader).

The hook you're looking for is here:
docutils/__init__.py::TransformSpec.unknown_reference_resolvers

For an example, see sandbox/mmgilbe/rst.py, the original
MoinMoin/Docutils interface code.

That helps significantly. I am going to give that a try. Never noticed that
before!



> P.S. An aside, parsers/rst/states.py has an unused
> UnknownInterpretedRoleError exception.

OK... Do you have a point, other than this showing up in linter output?

No, just found it. Wasn’t a linter, saw it, grep’d and saw it wasn’t
implemented, thought it’d be related to the question and wanted to mention.
Was a Chesterton’s fence to me.



David Goodger
<http://python.net/~goodger>