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!

[hoxbro]

I have seen a similar problem for docstrings but only for docstrings outside of functions. I have attached an example which is heavy inspired by prisaes, and by running the same line sphinx-build -b singlehtml -d _build/doctrees . _build/singlehtml i get the following for output:

If I delete ´:members:´ from manual.rst the docstring outside the function works as expected.

Am i doing anything wrong? I'm running the newest version (0.9.1).

[prisae]

Which version are you using? For me all problems are resolved from numpydoc version 0.9.0 onwards.

[hoxbro]

I'm using version numpydoc 0.9.1 and python 3.7.3. My attached example is not completely the same as your example.
Have you tried running my example? If not would it be possible for you to try doing it and post your results? Thanks in advanced.

[prisae]

Doesn't work for me either. I suggest you open a new issue, as this issue here was resolved. I don't now what is going in your case, I am sorry.

[prisae]

What do you get with numpydoc v0.6.0, v0.7.0, v0.8.0?