Test for autoapi extension. (#334)

Closes #327.

.github/workflows/build.yml

@@ -48,10 +48,6 @@ jobs:
           - python-version: '3.11'
             pip-sphinx: '"sphinx<7"'
             pytest-options: ''
-          # sphinx pre-release
-          - python-version: '3.11'
-            pip-sphinx: '--pre sphinx'
-            pytest-options: ''
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
@@ -62,7 +58,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install pytest codecov coverage
-        python -m pip install . ${{ matrix.pip-sphinx }}
+        python -m pip install . sphinx-autoapi ${{ matrix.pip-sphinx }}
     - name: Install extra dependencies
       run: |
         python -m pip install flake8 check-manifest mypy types-setuptools types-docutils

src/sphinxcontrib/bibtex/__init__.py

@@ -50,7 +50,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_role("footcite", FootCiteRole())
 
     return {
-        "version": "2.6.0a5",
+        "version": "2.6.0a6",
         "env_version": 9,
         "parallel_read_safe": True,
         "parallel_write_safe": True,

test/roots/test-autoapi/conf.py

@@ -0,0 +1,7 @@
+extensions = ["sphinxcontrib.bibtex", "autoapi.extension"]
+exclude_patterns = ["_build"]
+bibtex_bibfiles = ["test.bib"]
+autoapi_python_class_content = "both"  # document __init__ method too
+autoapi_dirs = ["some_module/"]
+autoapi_keep_files = True  # useful for debugging
+autoapi_add_toctree_entry = False

test/roots/test-autoapi/index.rst

@@ -0,0 +1,8 @@
+index
+=====
+
+.. toctree::
+
+   autoapi/some_module/index
+
+.. bibliography::

test/roots/test-autoapi/some_module/__init__.py

@@ -0,0 +1 @@
+"""Some module."""

test/roots/test-autoapi/some_module/footcite.py

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

test/roots/test-autoapi/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/roots/test-autodoc/doc_cite.rst

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

test/roots/test-autodoc/doc_footcite.rst

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

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/test_autoapi.py

@@ -0,0 +1,69 @@
+"""
+    test_autodoc
+    ~~~~~~~~~~~~
+
+    Test with autodoc.
+"""
+
+from test.common import (
+    html_citation_refs_single,
+    html_citations,
+    html_footnote_refs,
+    html_footnotes,
+)
+
+import pytest
+
+
+@pytest.mark.sphinx("html", testroot="autoapi")
+def test_autoapi(app, warning) -> None:
+    app.build()
+    assert not warning.getvalue()
+    root = (app.outdir / "index.html").read_text()
+    output = (app.outdir / "autoapi/some_module/cite/index.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_single(label=label).findall(output)) == 1
+        assert len(html_citations(label=label).findall(root)) == 1
+        match_ref = html_citation_refs_single(label=label).search(output)
+        match = html_citations(label=label).search(root)
+        assert match_ref
+        assert match
+        assert match_ref.group("refid") == match.group("id_")
+        assert title in match.group("text")
+        # no backrefs as citations are in other document
+        # assert match_ref.group("id_") == match.group("backref")
+    output2 = (app.outdir / "autoapi/some_module/footcite/index.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

test/test_autodoc.py

@@ -5,8 +5,8 @@
     Test with autodoc.
 """
 
-import test.some_module_cite
-import test.some_module_footcite
+import test.some_module.cite
+import test.some_module.footcite
 from test.common import (
     html_citation_refs_single,
     html_citations,
@@ -19,9 +19,9 @@
 
 # for coverage
 def test_some_module() -> None:
-    f1 = test.some_module_cite.Foo(0)
+    f1 = test.some_module.cite.Foo(0)
     assert f1.c == 3
-    f2 = test.some_module_footcite.Foo(0)
+    f2 = test.some_module.footcite.Foo(0)
     assert f2.c == 3