numpy / numpy/numpydoc

rename_references breaks whitespace for tables

Open
#130 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: Bug fix
Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

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...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at numpydoc/numpydoc.py around line 39, where footnote references are renamed, and reproduce the issue with footnote_in_table.py, footnote_in_table.rst, and conf.py using Sphinx. Preserve the table's whitespace during renaming so the build no longer reports a malformed table or unreferenced citations.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.