WIP: Add parameter class links

[larsoner]

It would be nice if the parameter list like:

n : int
    Number of time points.

Became this in Sphinx:

**n** : :class:`int`
    Number of time points

That would make it render properly and link to the proper class (with intersphinx), and for more complex types within a given module, it could nicely link to the proper classes.

The current implementation is not good, but shows something like what could be done eventually. Is this of interest to people?

[jnothman]

What you probably want is a config parameter containing a regexp for type names. This should be sufficient in practice to list exceptions (for those sufficiently expert in regex), except perhaps where abbreviations are needed (e.g. "array" short for "numpy.ndarray"). Rather than specialising for :class: or :const: you can use the role :obj: to catch all language objects. Personally, I'd like to be able to match any :obj: or :term: but I've not yet found Sphinx docs that says such a super-role exists.

Want to complete the PR?

[larsoner]

This should be sufficient in practice to list exceptions (for those sufficiently expert in regex), except perhaps where abbreviations are needed (e.g. "array" short for "numpy.ndarray")

If we can come up with a really good default regular expression that can cover 90% of use cases (or hopefully, to start, numpy and scipy doctstrings reasonably well at least), this seems like a good start. I guess it wouldn't limit future use cases anyway, as we could always set the regexp to be permissive if we added other options that overlapped with the regex exclusions.

For aliasing, adding e.g. an aliases=dict(ndarray=numpy.ndarray, array=numpy.ndarray) default dict and doing something like:

link_name = aliases.get(link_name, link_name))

Could be a pretty simple interface and work nicely.

Rather than specialising for :class: or :const: you can use the role :obj: to catch all language objects.

Neat, didn't realize that was an option.

Want to complete the PR?

Do you think it should be exclude_regex in which case something simple could be used, or include_regex which could use a negative lookaround solution? Or maybe both?

I could try to make some default, test it, and update the PR, sure. It might take me a bit because my regex skills aren't top-notch.

[jnothman]

Problem is that usually we're using things like array-like in which case a glossary's :term: is going to be more effective than a mapping. I would leave the aliasing out for now.

Perhaps a numpydoc_type_split_regex would be easier to read.

equivalent:

numpydoc_type_regex = r'(?!=(or|of|instance|optional))\b[^\W\d]\w+\b'
numpydoc_type_split_regex = r'\W|\b(or|of|instance|optional|\d+)\b'

[jnothman]

The :any: role might be what we want... (or make it configurable if need be)

[larsoner]

Problem is that usually we're using things like array-like in which case a glossary's :term: is going to be more effective than a mapping. I would leave the aliasing out for now.

What glossary do you mean?

Ideally maybe array-like should link to this page but I doubt there is a straightforward alias for it.

But regardless, array-like seems more like a concern for Parameters than Returns. The former can often take array-like, whereas the latter almost always will contain array / ndarray and not array-like. It seems like a shame to limit the ability to properly link such Returns values because the proposed solution wouldn't also take care of array-like. And in a few packages I work on, we don't really use array-like all that often in Parameters anyway, so it's not a huge loss not to have it.

[jnothman]

https://docs.scipy.org/doc/numpy-1.12.0/glossary.html#term-array-like would be linked to with

:any:`array-like`

or

:term:`array-like`

in numpy docs.

[jnothman]

Despite the brevity of the split regex, it's much harder to express exceptional inclusions (like allowing array-like to be matched despite its punctuation), so an inclusion regex is probably better

[jnothman]

The other thing that needs to be handled is ignoring already-markedup terms

[has2k1]

Is there any resolution on the way forward?

Here are lists of the unique field entries in numpy and scipy.

numpy-fields.txt
scipy-fields.txt

[larsoner]

No, but I think mostly someone needs to find time to make something reasonable work properly and we can iterate in subsequent PRs from there. (I haven't had time yet.)

[has2k1]

If it is okay with you I can takeover.

[larsoner]

Yep fine by me

[larsoner]

Closing for #150