Add test for numpydoc (#295)

.github/workflows/python-package.yml

@@ -15,16 +15,24 @@ jobs:
       matrix:
         python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11-dev']
         pip-sphinx: [sphinx]
+        pytest-options: ['-m "not numpydoc"']
         include:
+          # numpydoc tests
+          - python-version: '3.10'
+            pip-sphinx: 'sphinx numpydoc'
+            pytest-options: '-m "numpydoc"'
           # sphinx 2.1 (the oldest supported version, released for Python 3.7)
           - python-version: '3.7'
             pip-sphinx: '"sphinx==2.1" "docutils==0.16" "jinja2<3.1"'
+            pytest-options: '-m "not numpydoc"'
           # latest of sphinx 3.x series (released for Python 3.9)
           - python-version: '3.9'
             pip-sphinx: '"sphinx<4" "jinja2<3.1"'
+            pytest-options: '-m "not numpydoc"'
           # sphinx pre-release
           - python-version: '3.10'
             pip-sphinx: '--pre sphinx'
+            pytest-options: '-m "not numpydoc"'
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
@@ -59,5 +67,5 @@ jobs:
       if: matrix.pip-sphinx == 'sphinx' && matrix.python-version == '3.9'
     - name: Test with pytest
       run: |
-        coverage run -m pytest
+        coverage run -m pytest ${{ matrix.pytest-options }}
         codecov

doc/usage.rst

@@ -1023,6 +1023,21 @@ reference.
 This appears to be a limitation of the toctree directive.
 No workaround is currently known.
 
+Unknown Target Name When Using Footnote Citations With Numpydoc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Numpydoc will sometimes duplicate the short description (i.e. the first line
+of the docstring) of some python objects
+such as member functions. If it does that, and you have a footnote citation
+in the short description, Sphinx may not be able to properly resolve
+the footnote target.
+If this happens,
+the workaround is not to have footnote citations in the first line of
+your docstrings. Instead, put them in the long description.
+Alternatively, set ``numpydoc_class_members_toctree`` to ``False``
+in your ``conf.py`` file. This will cause numpydoc not to
+duplicate the short descriptions for class members.
+
 Import errors after using setup.py install
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

pytest.ini

@@ -2,3 +2,5 @@
 norecursedirs = doc src
 testpaths =
   test
+markers =
+  numpydoc: tests for the numpydoc extension, requires numpydoc to be installed

test/roots/test-autodoc/conf.py

@@ -1,6 +1,3 @@
-import os
-import sys
-sys.path.append(os.path.dirname(__file__))
 extensions = [
     'sphinxcontrib.bibtex', 'sphinx.ext.autodoc']
 exclude_patterns = ['_build']

test/roots/test-autodoc/doc_cite.rst

@@ -1,7 +1,7 @@
 cite
 ====
 
-.. automodule:: some_module_cite
+.. automodule:: test.some_module_cite
    :members:
 
 .. bibliography::

test/roots/test-autodoc/doc_footcite.rst

@@ -1,7 +1,7 @@
 footcite
 ========
 
-.. automodule:: some_module_footcite
+.. automodule:: test.some_module_footcite
    :members:
 
 .. footbibliography::

test/roots/test-numpydoc/conf.py

@@ -0,0 +1,5 @@
+extensions = [
+    'sphinxcontrib.bibtex', 'numpydoc']
+exclude_patterns = ['_build']
+bibtex_bibfiles = ['test.bib']
+autoclass_content = 'both'  # document __init__ method too

test/roots/test-numpydoc/doc_cite.rst

@@ -0,0 +1,8 @@
+cite
+====
+
+.. automodule:: test.some_module_cite
+   :members:
+
+.. bibliography::
+   :style: alpha

test/roots/test-numpydoc/doc_footcite.rst

@@ -0,0 +1,7 @@
+footcite
+========
+
+.. automodule:: test.some_module_footcite
+   :members:
+
+.. footbibliography::

test/roots/test-numpydoc/index.rst

@@ -0,0 +1,7 @@
+index
+=====
+
+.. toctree::
+
+   doc_cite
+   doc_footcite

test/roots/test-numpydoc/test.bib

@@ -0,0 +1,44 @@
+@Misc{testmodule,
+  author =    {A. One},
+  title =     {Een},
+}
+@Misc{testfunc,
+  author =    {B. Two},
+  title =     {Twee},
+}
+@Misc{testfuncarg,
+  author =    {C. Three},
+  title =     {Drie},
+}
+@Misc{testdata,
+  author =    {D. Four},
+  title =     {Vier},
+}
+@Misc{testclass,
+  author =    {E. Five},
+  title =     {Vijf},
+}
+@Misc{testclassattr,
+  author =    {F. Six},
+  title =     {Zes},
+}
+@Misc{testinstanceattr,
+  author =    {G. Seven},
+  title =     {Zeven},
+}
+@Misc{testinit,
+  author =    {H. Eight},
+  title =     {Acht},
+}
+@Misc{testinitarg,
+  author =    {I. Nine},
+  title =     {Negen},
+}
+@Misc{testmethod,
+  author =    {J. Ten},
+  title =     {Tien},
+}
+@Misc{testmethodarg,
+  author =    {K. Eleven},
+  title =     {Elf},
+}

test/some_module_cite.py

@@ -0,0 +1,52 @@
+"""Docstring for some_module. :cite:`testmodule`"""
+
+
+def func(funcarg):
+    """Docstring for function func.
+
+    Long description goes here. See :cite:`testfunc`.
+
+    :param funcarg: Docstring for parameter. :cite:`testfuncarg`
+    """
+
+
+a = 1
+"""Docstring for variable a.
+
+Long description goes here. See :cite:`testdata`.
+"""
+
+
+class Foo:
+    """Docstring for class Foo.
+
+    Long description goes here. See :cite:`testclass`.
+    """
+
+    b = 2
+    """Docstring for class attribute b.
+
+    Long description goes here. See :cite:`testclassattr`.
+    """
+
+    def __init__(self, initarg):
+        """Docstring for constructor.
+
+        Long description goes here. See :cite:`testinit`
+
+        :param initarg: Docstring for parameter. :cite:`testinitarg`
+        """
+
+        self.c = 3
+        """Docstring for instance attribute c.
+
+        Long description goes here. See :cite:`testinstanceattr`.
+        """
+
+    def method(self, methodarg):
+        """Docstring for method.
+
+        Long description goes here. See :cite:`testmethod`.
+
+        :param methodarg: Docstring for parameter. :cite:`testmethodarg`
+        """

test/some_module_footcite.py

@@ -0,0 +1,52 @@
+"""Docstring for some_module. :footcite:`testmodule`"""
+
+
+def func(funcarg):
+    """Docstring for function func.
+
+    Long description goes here. See :footcite:`testfunc`.
+
+    :param funcarg: Docstring for parameter. :footcite:`testfuncarg`
+    """
+
+
+a = 1
+"""Docstring for variable a.
+
+Long description goes here. See :footcite:`testdata`.
+"""
+
+
+class Foo:
+    """Docstring for class Foo.
+
+    Long description goes here. See :footcite:`testclass`.
+    """
+
+    b = 2
+    """Docstring for class attribute b.
+
+    Long description goes here. See :footcite:`testclassattr`.
+    """
+
+    def __init__(self, initarg):
+        """Docstring for constructor.
+
+        Long description goes here. See :footcite:`testinit`.
+
+        :param initarg: Docstring for parameter. :footcite:`testinitarg`
+        """
+
+        self.c = 3
+        """Docstring for instance attribute c.
+
+        Long description goes here. See :footcite:`testinstanceattr`
+        """
+
+    def method(self, methodarg):
+        """Docstring for method.
+
+        Long description goes here. See  :footcite:`testmethod`.
+
+        :param methodarg: Docstring for parameter. :footcite:`testmethodarg`
+        """

test/test_autodoc.py

@@ -8,9 +8,19 @@
 from test.common import (
     html_citation_refs, html_citations, html_footnote_refs, html_footnotes
 )
+import test.some_module_cite
+import test.some_module_footcite
 import pytest
 
 
+# for coverage
+def test_some_module() -> None:
+    f1 = test.some_module_cite.Foo(0)
+    assert f1.c == 3
+    f2 = test.some_module_footcite.Foo(0)
+    assert f2.c == 3
+
+
 @pytest.mark.sphinx('html', testroot='autodoc')
 def test_autodoc(app, warning) -> None:
     app.build()

test/test_numpydoc.py

@@ -0,0 +1,34 @@
+from test.common import (
+    html_citation_refs, html_citations, html_footnote_refs, html_footnotes
+)
+import pytest
+
+
+@pytest.mark.numpydoc
+@pytest.mark.sphinx('html', testroot='numpydoc')
+def test_numpydoc(app, warning) -> None:
+    app.build()
+    # assert not warning.getvalue()
+    output = (app.outdir / "doc_cite.html").read_text()
+    labels = ['One', 'Two', 'Thr', 'Fou', 'Fiv', 'Six', 'Sev', 'Eig', 'Nin',
+              'Ten', 'Ele']
+    titles = ['Een', 'Twee', 'Drie', 'Vier', 'Vijf', 'Zes', 'Zeven', 'Acht',
+              'Negen', 'Tien', 'Elf']
+    for label, title in zip(labels, titles):
+        assert len(html_citation_refs(label=label).findall(output)) == 1
+        assert len(html_citations(label=label).findall(output)) == 1
+        match_ref = html_citation_refs(label=label).search(output)
+        match = html_citations(label=label).search(output)
+        assert match_ref
+        assert match
+        assert match_ref.group('refid') == match.group('id_')
+        assert title in match.group('text')
+    output2 = (app.outdir / "doc_footcite.html").read_text()
+    assert len(html_footnote_refs().findall(output2)) == 11
+    for title in titles:
+        text = ".*" + title + ".*"
+        assert len(html_footnotes(text=text).findall(output2)) == 1
+        match = html_footnotes(text=text).search(output2)
+        assert match
+        id_ = match.group('id_')
+        assert len(html_footnote_refs(refid=id_).findall(output2)) == 1