rename_references breaks whitespace for tables

[peterjc]

Setup

Mac OS X, Python 3.6, Sphinx 1.6.5, numpydoc 0.7.0

$ python3 -msphinx --version
Sphinx (sphinx-build) 1.6.5
$ python3 -c "import numpydoc; print(numpydoc.__version__)"
0.7.0

Reproducible example

Test case, call this file footnote_in_table.py

"""This is a silly module using footnotes in a table.

This is a reStructuredText grid table:

+----------+--------------+
| Colour   | Animal       |
+==========+==============+
| Black    | Sheep        |
+----------+--------------+
| Red      | Fox [1]_     |
+----------+--------------+
| Brown    | Cow          |
+----------+--------------+
| Blue     | Whale        |
+----------+--------------+
| Green    | Sloth        |
+----------+--------------+
| Orange   | Tiger [2]_   |
+----------+--------------+
| Ginger   | Cat [999]_   |
+----------+--------------+

That was the table. Note it had footnotes.

.. [1] Perhaps Silver?

.. [2] I think of tigers as orange and black.

.. [999] Footnote numbering is arbitrary.

"""


class Silly(object):
    """Silly object."""

    def __str__(self):
        """Returns a silly string."""
        return "Very silly"


if __name__ == "__main__":
    s = Silly()
    print(s)

Call this file footnote_in_table.rst,

Module contents
---------------

.. automodule:: footnote_in_table
    :members:
    :undoc-members:
    :show-inheritance:

Minimal configuration file, conf.py,

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Minimal configuration file, created by hand
extensions = ['sphinx.ext.autodoc', 'numpydoc']
source_suffix = '.rst'
master_doc = 'footnote_in_table'

Failing output:

$ python3 -msphinx . html
Running Sphinx v1.6.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] footnote_in_table                                                                                                                       
/private/tmp/test_case/footnote_in_table.py:docstring of footnote_in_table:5: WARNING: Malformed table.

+----------+--------------+
| Colour   | Animal       |
+==========+==============+
| Black    | Sheep        |
+----------+--------------+
| Red      | Fox [R1]_     |
+----------+--------------+
| Brown    | Cow          |
+----------+--------------+
| Blue     | Whale        |
+----------+--------------+
| Green    | Sloth        |
+----------+--------------+
| Orange   | Tiger [R2]_   |
+----------+--------------+
| Ginger   | Cat [R999]_   |
+----------+--------------+
looking for now-outdated files... none found
pickling environment... done
checking consistency... /private/tmp/test_case/footnote_in_table.rst:25: WARNING: Citation [R1] is not referenced.
/private/tmp/test_case/footnote_in_table.rst:27: WARNING: Citation [R2] is not referenced.
/private/tmp/test_case/footnote_in_table.rst:29: WARNING: Citation [R999] is not referenced.
done
preparing documents... done
writing output... [100%] footnote_in_table                                                                                                                        
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 4 warnings.

Diagnosis

While renaming the footnote references the importance of white space is not considered here:

https://github.com/numpy/numpydoc/blob/v0.7.0/numpydoc/numpydoc.py#L39

Suggested fix pending...

[peterjc]

Workaround, use R# style in the source:

"""This is a silly module using footnotes in a table.

This is a reStructuredText grid table:

+----------+--------------+
| Colour   | Animal       |
+==========+==============+
| Black    | Sheep        |
+----------+--------------+
| Red      | Fox [R1]_    |
+----------+--------------+
| Brown    | Cow          |
+----------+--------------+
| Blue     | Whale        |
+----------+--------------+
| Green    | Sloth        |
+----------+--------------+
| Orange   | Tiger [R2]_  |
+----------+--------------+
| Ginger   | Cat [R999]_  |
+----------+--------------+

That was the table. Note it had footnotes.

.. [R1] Perhaps Silver?

.. [R2] I think of tigers as orange and black.

.. [R999] Footnote numbering is arbitrary.

"""


class Silly(object):
    """Silly object."""

    def __str__(self):
        """Returns a silly string."""
        return "Very silly"


if __name__ == "__main__":
    s = Silly()
    print(s)

[peterjc]

Alternative workaround: Use the symbol footnotes rather than numbered ones.