0 appended to reference id when called by automodule

[momargoh]

Subject: 0 appended to reference id when called by automodule

Problem

In my project root I have dirs for docs/, examples/ and src/. In docs/ I have an .rst file that uses automodule to print the docstring of a module in the examples directory. In this docstring is a citation of a reference as below.

This example goes over the analysis found in the author's paper [Author2018]_.

.. [Author2018] Author, T., Rest of the reference, 2018

When I compile my docs to .html the reference appears with an appended 0, ie:

This example goes over the analysis found in the author's paper [Author20180].
[Author20180] | Author, T., Rest of the reference, 2018

Procedure to reproduce the problem

I am using python3-sphinx: sudo apt install python3-sphinx and then simply running make html in docs/.

make html

Error logs / results

No error log is produced.

Expected results

The reference appears as in the docstring: without the appended 0.

Reproducible project / your project

I have attached a zip of a mock project demonstrating the problem.
example_project.zip

Environment info

• OS: Ubuntu 17.10 (same result on Ubuntu 16.04)
• Python version: 3.6.3
• Sphinx version: 1.5.6

[jfbu]

Thanks for reporting and the attached mock project. Same with Sphinx 1.6.6 and 1.7.2.
With provided https://github.com/sphinx-doc/sphinx/files/1846112/example_project.zip I can reproduce still after commenting out extensions in conf.py like that:

extensions = [
    'sphinx.ext.autodoc',
#    'sphinx.ext.doctest',
#    'sphinx.ext.intersphinx',
#    'sphinx.ext.todo',
#    'sphinx.ext.coverage',
#    'sphinx.ext.mathjax',
#    'sphinx.ext.ifconfig',
#    'sphinx.ext.viewcode',
#    'sphinx.ext.autosummary',
#    'sphinx.ext.githubpages',
    'numpydoc'
]

and the problem disappears when commenting out 'numpydoc'.

It appears numpydoc does some reference renaming (see thread at numpy/numpydoc#136).

@jnothman can you please give a look? perhaps this is an issue known to numpydoc project or which should be reported there.

@momargoh thanks a lot for the mock project. I will examine later if blame is to put more on numpydoc or Sphinx ;-), awaiting @jnothman's advice.

[jnothman]

It's a known feature ...uhh... hack. numpy/numpydoc#136 should fix the rendering in HTML, but makes a problem of TeX​, which is one reason it's not been merged.

[jnothman]

The problem that numpydoc is trying to solve is to have each reference scoped locally, to the docstring. This allows for repeated references, and for footnote notation to be used for references within a docstring. But then numpydoc mangles the references to make sure there are no conflicts. I think it used to do it less aggressively, but the current numpydoc release, which is the one I started hacking, is pretty aggressive about it.

[jfbu]

@jnothman thanks for these explanations. I need to go see how this is done at numpydoc currently. Regarding Sphinx + tex, it is planned that Sphinx will use in future normal \cite.

[momargoh]

@jnothman thanks a lot for the explanation, good to have that clarified.

[jnothman]

Currently we mangle the reST and destroy tables and all kinds of bad. The PR attempts to change the reference id but not the text.

[jfbu]

Adding this link to relevant numpydoc issue.

[jfbu]

side-note, I wanted to try out with sphinx latexpdf, there was an error. Turns out, to fix it I had to escape the underscore from LaTeX in document title. Here is the fix:

latex_documents = [(master_doc, 'example_project.tex',
                    'example\\_project Documentation', 'Your Name', 'manual'),
                   ]

cf the doc for "title" in LaTeX:

title: LaTeX document title. Can be empty to use the title of the startdoc. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.

[jfbu]

@jnothman could you please give a look at https://github.com/jfbu/numpydoc/tree/disambiguate-undecorate-refs. This is a follow-up to your numpy/numpydoc#136. The idea is to keep some de-ambiguating in final result. In my brief testing on very minimal project this works fine for html and latex. Perhaps the -<number> postfix should be a letter.

I used the https://github.com/sphinx-doc/sphinx/files/1846112/example_project.zip provided by @momargoh. For latexpdf I first applied the above fix.

I had a problem that the docstring of example.py was not recognized as such, hence was skipped by your relabel_references(app, doc). I needed to comment out a conditional in it to force execution, and I have not investigated more (because I am no expert in Docutils internals). I added a few more docstrings where I used footnote style for citations (as seems to be the numpydoc way), to have duplicates and see how it came out. Probably you will have handy bigger test project.

I am commenting here and not at numpydoc because I feel I do not quite understand the numpydoc framework so it feels more cozy here.

[jnothman]

So that affects the display of the references when ambiguous, and also fixes LaTeX? I suppose that's worthwhile. I might be happier if the display is unaffected, but at least this would be a good step towards merge. The code you commented out: I can't remember what it was for but presumably you think it is unnecessary