Add gp-libs: Test docs via doctest, table of contents for sphinx.ext.autodoc, change issues module

.github/workflows/tests.yml

@@ -68,6 +68,7 @@ jobs:
           export PATH=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin:$PATH
           ls $HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin
           tmux -V
+          sudo apt install cowsay
           poetry run py.test --cov=./ --cov-append --cov-report=xml
         env:
           COV_CORE_SOURCE: .

CHANGES

@@ -29,10 +29,18 @@ $ pip install --user --upgrade --pre libtmux
 - Add [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) (#408)
 - Add [flake8-comprehensions](https://github.com/adamchainz/flake8-comprehensions) (#409)
 
+### Tests
+
+- Test doctests in documentation via
+  [pytest-doctest-docutils](https://gp-libs.git-pull.com/doctest/pytest.html) (#410)
+
 ### Documentation
 
 - Move to sphinx-autoissues, #406
 - Examples updated for correctness, #412 (cherry-picked from #410)
+- Render changelog in [linkify_issues](https://gp-libs.git-pull.com/linkify_issues/) (#410)
+- Fix Table of contents rendering with sphinx autodoc with
+  [sphinx_toctree_autodoc_fix](https://gp-libs.git-pull.com/sphinx_toctree_autodoc_fix/) (#410)
 
 ## libtmux 0.14.2 (2022-08-17)
 

Makefile

@@ -1,4 +1,6 @@
 PY_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]py$$' 2> /dev/null
+DOC_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]rst\$\|.*[.]md\$\|.*[.]css\$\|.*[.]py\$\|mkdocs\.yml\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
+ALL_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]py\$\|.*[.]rst\$\|.*[.]md\$\|.*[.]css\$\|.*[.]py\$\|mkdocs\.yml\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
 
 
 entr_warn:
@@ -22,7 +24,7 @@ start:
 	$(MAKE) test; poetry run ptw .
 
 watch_test:
-	if command -v entr > /dev/null; then ${PY_FILES} | entr -c $(MAKE) test; else $(MAKE) test entr_warn; fi
+	if command -v entr > /dev/null; then ${ALL_FILES} | entr -c $(MAKE) test; else $(MAKE) test entr_warn; fi
 
 build_docs:
 	$(MAKE) -C docs html

README.md

@@ -157,19 +157,18 @@ Grab the output of pane:
 ```python
 >>> pane.clear()  # clear the pane
 >>> pane.send_keys("cowsay 'hello'", enter=True)
->>> import time; time.sleep(1)
->>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))
-```
-
-    sh-3.2$ cowsay 'hello'
-     _______
-    < hello >
-     -------
-            \   ^__^
-             \  (oo)\_______
-                (__)\       )\/\
-                    ||----w |
-                    ||     ||
+>>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))  # doctest: +SKIP
+$ cowsay 'hello'
+ _______
+< hello >
+ -------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+...
+```
 
 Traverse and navigate:
 

docs/conf.py

@@ -22,19 +22,19 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    "autoapi.extension",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinx.ext.todo",
     "sphinx.ext.linkcode",
     "sphinx.ext.napoleon",
-    "sphinx_autoissues",
     "sphinx_click.ext",  # sphinx-click
     "sphinx_inline_tabs",
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
     "myst_parser",
+    "linkify_issues",
+    "sphinx_toctree_autodoc_fix",
 ]
 
 myst_enable_extensions = [
@@ -94,21 +94,14 @@
     ]
 }
 
-# sphinx-autoissues
-issuetracker = "github"
-issuetracker_project = about["__github__"].replace("https://github.com/", "")
+# linkify_issues
+issue_url_tpl = f'{about["__github__"]}/issues/{{issue_id}}'
 
 # sphinx.ext.autodoc
 autoclass_content = "both"
 autodoc_member_order = "bysource"
 autosummary_generate = True
 
-# sphinx-autoapi
-autoapi_type = "python"
-autoapi_dirs = [project_root / "libtmux"]
-autoapi_generate_api_docs = False  # when fales, use directives
-suppress_warnings = ["autoapi.python_import_resolution", "autoapi.not_readable"]
-
 # sphinx-copybutton
 copybutton_prompt_text = (
     r">>> |\.\.\. |> |\$ |\# | In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "

docs/internals/test.md

@@ -1,6 +1,6 @@
 # Test helpers
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.test
+.. automodule:: libtmux.test
    :members:
 ```

docs/pytest-plugin.md

@@ -87,12 +87,10 @@ object lookups in the test grid.
 ## API reference
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.pytest_plugin
+.. automodule:: libtmux.pytest_plugin
     :members:
     :inherited-members:
     :private-members:
     :show-inheritance:
     :member-order: bysource
-    :exclude-members: Server, TEST_SESSION_PREFIX, get_test_session_name,
-        namer, logger
 ```

docs/reference/common.md

@@ -1,6 +1,6 @@
 # Utilities
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.common
+.. automodule:: libtmux.common
    :members:
 ```

docs/reference/exceptions.md

@@ -1,6 +1,6 @@
 # Exceptions
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.exc
+.. automodule:: libtmux.exc
    :members:
 ```

docs/reference/panes.md

@@ -10,7 +10,7 @@
 [pty(4)]: https://www.freebsd.org/cgi/man.cgi?query=pty&sektion=4
 
 ```{eval-rst}
-.. autoapiclass:: libtmux.Pane
+.. autoclass:: libtmux.Pane
     :members:
     :inherited-members:
     :private-members:

docs/reference/servers.md

@@ -10,7 +10,7 @@
 tmux initializes a server on automatically on first running (e.g. executing `tmux`)
 
 ```{eval-rst}
-.. autoapiclass:: libtmux.Server
+.. autoclass:: libtmux.Server
     :members:
     :inherited-members:
     :private-members:

docs/reference/sessions.md

@@ -7,7 +7,7 @@
 - Identified by `$`, e.g. `$313`
 
 ```{eval-rst}
-.. autoapiclass:: libtmux.Session
+.. autoclass:: libtmux.Session
     :members:
     :inherited-members:
     :private-members:

docs/reference/windows.md

@@ -11,7 +11,7 @@
 ```
 
 ```{eval-rst}
-.. autoapiclass:: Window
+.. autoclass:: Window
     :members:
     :inherited-members:
     :private-members: