Unnecessary renaming of references

[astrofrog]

Numpydoc now renames references even when this is not needed. For example, a reference originally called Scargle2012 has now been renamed in the Astropy docs:

Is this intentional? Should we be using only numerical reference names? Or is it a bug since there are no duplicates of this reference so no reason to rename it?

[stefanv]

This is not necessary. The initial de-duplication script used numerical references for simplicity, but there's no reason why that has to be the case.

[astrofrog]

@stefanv - ok, thanks! Just to be clear, in this case this may actually be a regression since in the rest of the docstring the reference is referred to by Scargle2012_ and those references were not updated, so now give warnings when building the docs.

[stefanv]

I just read the code, and it does special case for anything other than numeric references. I guess it will transform it to something like Scargle20120. What warning do you see?

[astrofrog]

Basically I think it doesn't rename the Scargle2012_ reference in the text of the docstring so I saw an 'undefined reference' warning. Note that in the interest of time I just changed that reference to a numerical one, so this is not an issue for me anymore.

[jnothman]

@astrofrom shouldn't you be referring to it by [Scargle2012]_ rather than Scargle2012_?

Still, there's no way to determine if there will be a duplicate and also mangle the references in a single pass over the docstrings. We could allow the first appearance of a reference to not be mangled, if there is little risk in tracking all references ever mentioned. We could also insert some delimiter between the existing reference and the added number in the non-numeric case.

[jnothman]

ok, thanks! Just to be clear, in this case this may actually be a regression since in the rest of the docstring the reference is referred to by Scargle2012_ and those references were not updated, so now give warnings when building the docs.

The mangling here should only affect those references that are listed with .. [xxx] in the docstring...