References messed up

[prisae]

Version 0.8.0 of numpydoc supposedly fixed the referencing issue, but in my case it got worse, and I wonder why (related to #114).

---

With numpydoc v0.6.0 I get the following:

So for instance [Key_2012]: author_year, exactly what I intended to do.

---

With numpydoc v0.7.0 I get the following:

So it added a '0' to each reference.

---

But now with numpydoc v0.8.0 I get the following:

I assume that is not as was intended with the bugfix in #136?

---

Should I change the way I use references, or is this a bug that persists in numpydoc?

I have in readthedocs numpydoc fixed to 0.6.0, but if it helps the complete manual is here: http://empymod.readthedocs.io

Details regarding the build using conda (and pip for sphinxcontrib-napoleon) with Python 3.6:

numpydoc v0.8.0 and numpydoc v0.7.0:
sphinx 1.7.4; sphinxcontrib 1.0; sphinxcontrib-napoleon 0.6.1.

numpydoc v0.6.0
sphinx 1.6.6; sphinxcontrib 1.0; sphinxcontrib-napoleon 0.6.1.

[jnothman]

hmm. i can't investigate now but I'd be looking at interaction with other sphinx plugins, perhaps also sphinx and docutils version but I suspect that's not the issue.

[prisae]

I created a minimal example, called numpydoctest. Running 'tree' in numpydoctest:

numpydoctest/> tree
.
├── conf.py
├── index.rst
├── manual.rst
└── numpydoctest
    └── __init__.py

conf.py:

extensions = ['sphinx.ext.autodoc', 'numpydoc',]
master_doc = 'index'

index.rst:

.. toctree::
   manual

manual.rst:

.. automodule:: numpydoctest

numpydoctest/__init__.py:

"""

[Name_Year]_

[Test_2018]_

References
----------

.. [Name_Year] Name, Year, This is a test publication: The Journal.
.. [Test_2018] Test, 2018, A follow up: The Other Journal.

"""

Creating the docs with sphinx-build -b singlehtml -d _build/doctrees . _build/singlehtml yields the following:

In this minimum example I only use the extensions sphinx.ext.autodoc and numpydoc.

I add here this working minimal example for testing purposes:
numpydoctest.zip

[prisae]

I found the source of the problem. Well, kind of. In the above minimal example, if I change

extensions = ['sphinx.ext.autodoc', 'numpydoc',]

to

extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon',]

then all is fine.

Similarly, I change in my project from

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'numpydoc',
    'sphinxcontrib.napoleon',
]

to

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'sphinxcontrib.napoleon',
]

and now everything is smooth and beautiful.

Any idea why this could be?

[pv]

numpydoc is not napoleon, so let's keep this open for here.

[prisae]

Ok, it is probably good to get to the bottom of it.

I thought an issue could have been that I used numpydoc together with napoleon?

Indeed; it fixed the citation issue, but because I removed numpydoc it screwed up some of the formatting...

[jnothman]

The numpydoctest example seems to fail in the reference mangling due to two issues we'd not considered:

1. ~~doctree-read hooks only apply when sphinx-build is called with -d (which it is in the default makefiles). It is a bit weird that the output can be modified by something that is an optional hook :~~
2. We rely on the idea that I citation is in a docstring iff it has a desc node in its ancestry. It seems that may not always be the case. In particular, it appears that this reference in a module docstring is not in desc. The document node looks like:

<document source="/Users/joel/repos/numpydoc/numpydoctest/manual.rst">
  <target ids="['module-numpydoctest']" ismod="True" />
  <index entries="[('single', 'numpydoctest (module)', 'module-numpydoctest', '', None)]" />
  <paragraph>
    <pending_xref ids="id1" refdomain="std"
    reftarget="R8432db73336c-Name_Year" reftype="citation"
    refwarn="True">[R8432db73336c-Name_Year]</pending_xref>
  </paragraph>
  <paragraph>
    <pending_xref ids="id2" refdomain="std"
    reftarget="R8432db73336c-Test_2018" reftype="citation"
    refwarn="True">[R8432db73336c-Test_2018]</pending_xref>
  </paragraph>
  <section ids="references" names="references">
    <title>References</title>
    <citation backrefs="id1" ids="r8432db73336c-name-year"
    names="r8432db73336c-name_year">
      <label>R8432db73336c-Name_Year</label>
      <paragraph>Name, Year, This is a test publication: The
      Journal.</paragraph>
    </citation>
    <citation backrefs="id2" ids="r8432db73336c-test-2018"
    names="r8432db73336c-test_2018">
      <label>R8432db73336c-Test_2018</label>
      <paragraph>Test, 2018, A follow up: The Other
      Journal.</paragraph>
    </citation>
    <comment xml:space="preserve">
!! processed by numpydoc !!
</comment>
  </section>
</document>

[jnothman]

We could probably determine whether we're in a numpydoc docstring by exploiting that "!! processed by numpydoc !!" comment. I might get around to submitting a PR.

Alternatively, maybe we're wrong to be renaming references in modules at all...???

[jnothman]

My claim above about doctree-read depending on -d seems to have been incorrect.

[prisae]

Just tested it and it works fine for me, thanks!