docs: Use gp-libs for doc helpers (#410)

tony · web-flow · commit 3de3cc1d86d2 · 2022-09-10T10:11:54.000-05:00
## Changes Add gp-libs (https://github.com/git-pull/gp-libs, https://gp-libs.git-pull.com/, https://pypi.org/project/gp-libs/) - Render changelog in linkify_issues, https://gp-libs.git-pull.com/linkify_issues/ - Fix Table of contents rendering with sphinx autodoc with sphinx_toctree_autodoc_fix, https://gp-libs.git-pull.com/sphinx_toctree_autodoc_fix/ - Test documentation doctests (markdown) via pytest-doctest-docutils https://gp-libs.git-pull.com/doctest/pytest.html
diff --git a/.github/workflows/tests.yml b/.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: .
diff --git a/CHANGES b/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)
 
diff --git a/Makefile b/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
diff --git a/README.md b/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:
 
diff --git a/docs/conf.py b/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}: "
diff --git a/docs/internals/test.md b/docs/internals/test.md
@@ -1,6 +1,6 @@
 # Test helpers
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.test
+.. automodule:: libtmux.test
    :members:
 ```
diff --git a/docs/pytest-plugin.md b/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
 ```
diff --git a/docs/reference/common.md b/docs/reference/common.md
@@ -1,6 +1,6 @@
 # Utilities
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.common
+.. automodule:: libtmux.common
    :members:
 ```
diff --git a/docs/reference/exceptions.md b/docs/reference/exceptions.md
@@ -1,6 +1,6 @@
 # Exceptions
 
 ```{eval-rst}
-.. autoapimodule:: libtmux.exc
+.. automodule:: libtmux.exc
    :members:
 ```
diff --git a/docs/reference/panes.md b/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:
diff --git a/docs/reference/servers.md b/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:
diff --git a/docs/reference/sessions.md b/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:
diff --git a/docs/reference/windows.md b/docs/reference/windows.md
@@ -11,7 +11,7 @@
 ```
 
 ```{eval-rst}
-.. autoapiclass:: Window
+.. autoclass:: Window
     :members:
     :inherited-members:
     :private-members:
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/setup.cfg b/setup.cfg
