docs: sphinx-autoapi (#367)

Author: tony

CHANGES

@@ -18,6 +18,10 @@ $ pip install --user --upgrade --pre libtmux
 
   This created issues with running poetry while inside the virtualenv.
 
+### Documentation
+
+- Try out sphinx-autoapi for its table of contents generation ({issue}`367`)
+
 ## libtmux 0.11.0 (2022-03-10)
 
 ### Compatibility

docs/api.md

@@ -16,7 +16,7 @@ versions.
 ## Server Object
 
 ```{eval-rst}
-.. autoclass:: Server
+.. autoapiclass:: Server
     :members:
     :inherited-members:
     :private-members:
@@ -27,7 +27,7 @@ versions.
 ## Session Object
 
 ```{eval-rst}
-.. autoclass:: Session
+.. autoapiclass:: Session
     :members:
     :inherited-members:
     :private-members:
@@ -38,7 +38,7 @@ versions.
 ## Window Object
 
 ```{eval-rst}
-.. autoclass:: Window
+.. autoapiclass:: Window
     :members:
     :inherited-members:
     :private-members:
@@ -49,7 +49,7 @@ versions.
 ## Pane Object
 
 ```{eval-rst}
-.. autoclass:: Pane
+.. autoapiclass:: Pane
     :members:
     :inherited-members:
     :private-members:
@@ -68,22 +68,22 @@ versions.
 ```
 
 ```{eval-rst}
-.. autoclass:: libtmux.common.TmuxRelationalObject
+.. autoapiclass:: libtmux.common.TmuxRelationalObject
     :members:
 ```
 
 ```{eval-rst}
-.. autoclass:: libtmux.common.TmuxMappingObject
+.. autoapiclass:: libtmux.common.TmuxMappingObject
     :members:
 ```
 
 ```{eval-rst}
-.. autoclass:: libtmux.common.EnvironmentMixin
+.. autoapiclass:: libtmux.common.EnvironmentMixin
     :members:
 ```
 
 ```{eval-rst}
-.. autoclass:: libtmux.common.tmux_cmd
+.. autoapiclass:: libtmux.common.tmux_cmd
 ```
 
 ```{eval-rst}
@@ -187,7 +187,7 @@ versions.
 ```
 
 ```{eval-rst}
-.. autoclass:: libtmux.test.EnvironmentVarGuard
+.. autoapiclass:: libtmux.test.EnvironmentVarGuard
 ```
 
 ## Environmental variables

docs/conf.py

@@ -22,6 +22,7 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "autoapi.extension",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinx.ext.todo",
@@ -96,6 +97,17 @@
 ogp_desscription_length = about["__description__"]
 ogp_site_name = about["__title__"]
 
+# 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/reference/panes.md

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

docs/reference/servers.md

@@ -11,8 +11,7 @@ In tmux, a server is automatically started on your behalf
 when you first run tmux.
 
 ```{eval-rst}
-.. autoclass:: libtmux.Server
-    :noindex:
+.. autoapiclass:: libtmux.Server
     :members:
     :inherited-members:
     :private-members:

docs/reference/sessions.md

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

docs/reference/windows.md

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

poetry.lock

@@ -53,6 +53,7 @@ sphinx-inline-tabs = "*"
 sphinxext-opengraph = "*"
 sphinx-copybutton = "^0.5.0"
 sphinxext-rediraffe = "*"
+sphinx-autoapi = "^1.8.4"
 myst_parser = "~0.17.0"
 
 ### Testing ###
@@ -74,7 +75,7 @@ isort = "*"
 flake8 = "*"
 
 [tool.poetry.extras]
-docs = ["sphinx", "sphinx-issues", "sphinx-autodoc-typehints", "sphinx-autobuild", "sphinx-copybutton", "sphinxext-opengraph", "sphinx-inline-tabs", "sphinxext-rediraffe", "myst_parser", "furo"]
+docs = ["sphinx", "sphinx-issues", "sphinx-autoapi", "sphinx-autodoc-typehints", "sphinx-autobuild", "sphinx-copybutton", "sphinxext-opengraph", "sphinx-inline-tabs", "sphinxext-rediraffe", "myst_parser", "furo"]
 test = ["pytest", "pytest-rerunfailures", "pytest-mock", "pytest-watcher"]
 coverage = ["codecov", "coverage", "pytest-cov"]
 format = ["black", "isort"]