New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rename_references breaks whitespace for tables #130

Open
peterjc opened this Issue Oct 25, 2017 · 2 comments

Comments

Projects
None yet
2 participants
@peterjc

peterjc commented Oct 25, 2017

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

This comment has been minimized.

peterjc commented Oct 25, 2017

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

This comment has been minimized.

peterjc commented Oct 25, 2017

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

peterjc added a commit to peterjc/biopython that referenced this issue Oct 25, 2017

peterjc added a commit to peterjc/biopython that referenced this issue Oct 25, 2017

@jnothman jnothman added the bug label Oct 26, 2017

peterjc added a commit to biopython/biopython that referenced this issue Oct 30, 2017

MarkusPiotrowski added a commit to MarkusPiotrowski/biopython that referenced this issue Oct 31, 2017

jnothman added a commit to jnothman/numpydoc that referenced this issue Nov 1, 2017

jnothman added a commit that referenced this issue Mar 28, 2018

Ensure reference renaming is parallel-safe (#136)
* Ensure reference renaming is parallel-safe

This prefixes each reference with a token indicative of which docstring it belongs to and then relabels the text of the reference once the doctree is compiled

* Fix missing argument

* Install pdflatex in Travis

* More TeX packages

* Some sphinx require latexmk

* Move imports

* Fix comment

* Warn about #130

* Fixes to relabelling of references:

* Use label text not normalised text
* Split at first - not last
* Do not relabel non-docstring content

* Fix logic for identifying non-docscring
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment