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

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

On Sun, Sep 24, 2017 at 8:41 PM, Tony N <to...@gi...> wrote:
>
> 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.
>

What would do the catching?

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
>

"Transform", not "transformer". No Autobots or Decepticons allowed here; we
don't serve their kind.


> - 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
>

Not supported in Docutils.


> (I guess the simplest solution is to write a pure-docutils class role?)
>

If you want a role to do some special processing, you have to implement it.
So, yes.


> I may end up having to port “domains” from sphinx to being a pure docutils
> extension at that rate.
>

No idea what that means.


> 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?)
>

The role name is passed to the role code, if that's what you're asking.

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