Prefix added to reference keys in class docstrings

[rtavenar]

This is related to tslearn-team/tslearn#238 .

We use numpydoc for our documentation at tslearn and we love it! Thanks for the great tool!

When we build our documentation, it seems that instances of bibliographic references in class docstrings are attached some random prefix.

Corresponding docstring is:

    """A convenience class to access UCR/UEA time series datasets.

    When using one (or several) of these datasets in research projects, please
    cite [1]_.

    Parameters
    ----------
    use_cache : bool (default: True)
        Whether a cached version of the dataset should be used, if found.

    Notes
    -----
        Downloading dataset files can be time-consuming, it is recommended
        using `use_cache=True` (default) in order to
        only experience downloading time once per dataset and work on a cached
        version of the datasets after it.

    References
    ----------
    .. [1] A. Bagnall, J. Lines, W. Vickers and E. Keogh, The UEA & UCR Time
       Series Classification Repository, www.timeseriesclassification.com
    """

hence we would expect the generated key to be [1] not [R23f7...-1]

This does not happen when using the exact same formatting for the docstring in another place (e.g. in method docstrings). Is it expected behaviour? Is there a known fix for this?

[jnothman]

Hmm... these hashes were added to avoid identifier conflicts... But they should be removed by relabel_references (see

numpydoc/numpydoc/numpydoc.py

Line 224 in b4c5fd1

app.connect('doctree-read', relabel_references)

)

I initially wondered if these links have been escaped twice, but looking at the URL linked to in https://tslearn.readthedocs.io/en/stable/gen_modules/datasets/tslearn.datasets.UCR_UEA_datasets.html, I suspect not.

[jnothman]

So my question is: why is relabel_references not processing this node? we'd probably need to do some tracing to work it out.

[rtavenar]

I'd love to help if I can. Do not hesitate to indicate the kind of test I could run on my side.

[jnothman]

I'd probably start with adding some logging in relabel_references, then rebuilding the tslearn docs...

[rtavenar]

OK, it seems in my (and reathedocs') version of numpydoc (v0.9.1) the _is_cite_in_numpydoc_docstring would return False for this docstring. If I patchthis function with the version that is available on master, the references are found and the reformatted as expected.
I will hence move to a more up-to-date version of numpydoc and let you know, but this issue is probably already fixed, sorry for the inconvenience :/

[jnothman]

No worries!

[jnothman]

Likely fixed in #259.

[jnothman]

Unfortunately not yet released.

[rtavenar]

It works!
(I just had to tell RTD to look for numpydoc in this repo's master rather than on PyPI)

Thanks for your help!