diff --git a/CHANGES b/CHANGES index 70d5ab7a594..c11549aab5a 100644 --- a/CHANGES +++ b/CHANGES @@ -27,6 +27,11 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force - `config_reader`: Move to `tmuxp._internal` (#897) - `_types`: Move to `tmuxp._internal` (#900) +### Documentation + +- Refactor API docs to split across multiple pages (#898) +- Remove unused reStructuredText section headers from some modules (#898) + ## tmuxp 1.33.0 (2023-12-21) _Maintenance only, no bug fixes or new features_ diff --git a/docs/_ext/aafig.py b/docs/_ext/aafig.py index b0f0b284cc1..d6e5ba06af7 100644 --- a/docs/_ext/aafig.py +++ b/docs/_ext/aafig.py @@ -1,6 +1,6 @@ """aafig plugin for sphinx. -sphinxcontrib.aafig. +sphinxcontrib.aafig ~~~~~~~~~~~~~~~~~~~ Allow embedded ASCII art to be rendered as nice looking images diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index eb8c67a5957..00000000000 --- a/docs/api.md +++ /dev/null @@ -1,149 +0,0 @@ -(api)= - -# API Reference - -:::{seealso} -See {ref}`libtmux's API ` and {ref}`Quickstart ` to see how you can control -tmux via python API calls. -::: - -## Internals - -:::{warning} -Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions. - -If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues). -::: - -```{eval-rst} -.. automethod:: tmuxp.util.run_before_script -``` - -```{eval-rst} -.. automethod:: tmuxp.util.oh_my_zsh_auto_title -``` - -```{eval-rst} -.. automethod:: tmuxp.util.get_current_pane -``` - -```{eval-rst} -.. automethod:: tmuxp.util.get_session -``` - -```{eval-rst} -.. automethod:: tmuxp.util.get_window -``` - -```{eval-rst} -.. automethod:: tmuxp.util.get_pane -``` - -## CLI - -```{eval-rst} -.. automethod:: tmuxp.cli.import_config.get_teamocil_dir -``` - -```{eval-rst} -.. automethod:: tmuxp.cli.import_config.get_tmuxinator_dir -``` - -```{eval-rst} -.. automethod:: tmuxp.cli.load.load_workspace -``` - -```{eval-rst} -.. automethod:: tmuxp.cli.load._reattach -``` - -## Workspace files - -### Finding - -```{eval-rst} -.. automethod:: tmuxp.workspace.finders.is_workspace_file -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.finders.in_dir -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.finders.in_cwd -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.finders.get_workspace_dir -``` - -### Validation - -```{eval-rst} -.. autofunction:: tmuxp.workspace.validation.validate_schema -``` - -### Processing - -```{eval-rst} -.. automethod:: tmuxp.workspace.loader.expandshell -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.loader.expand -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.loader.trickle -``` - -## Workspace importers - -```{eval-rst} -.. automethod:: tmuxp.workspace.importers.import_teamocil -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.importers.import_tmuxinator -``` - -## Configuration reader - -```{eval-rst} -.. automodule:: tmuxp._internal.config_reader -``` - -## Workspace Builder - -```{eval-rst} -.. autoclass:: tmuxp.workspace.builder.WorkspaceBuilder - :members: -``` - -## Workspace Freezer - -```{eval-rst} -.. automethod:: tmuxp.workspace.freezer.freeze -``` - -```{eval-rst} -.. automethod:: tmuxp.workspace.freezer.inline -``` - -## Exceptions - -```{eval-rst} -.. autoexception:: tmuxp.exc.EmptyWorkspaceException -``` - -```{eval-rst} -.. autoexception:: tmuxp.exc.WorkspaceError -``` - -```{eval-rst} -.. autoexception:: tmuxp.exc.BeforeLoadScriptError -``` - -```{eval-rst} -.. autoexception:: tmuxp.exc.BeforeLoadScriptNotExists -``` diff --git a/docs/api/cli/convert.md b/docs/api/cli/convert.md new file mode 100644 index 00000000000..4c9b87f34f6 --- /dev/null +++ b/docs/api/cli/convert.md @@ -0,0 +1,8 @@ +# tmuxp convert - `tmuxp.cli.convert` + +```{eval-rst} +.. automodule:: tmuxp.cli.convert + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/debug_info.md b/docs/api/cli/debug_info.md new file mode 100644 index 00000000000..56a50052e66 --- /dev/null +++ b/docs/api/cli/debug_info.md @@ -0,0 +1,8 @@ +# tmuxp debug-info - `tmuxp.cli.debug_info` + +```{eval-rst} +.. automodule:: tmuxp.cli.debug_info + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/edit.md b/docs/api/cli/edit.md new file mode 100644 index 00000000000..704e8144c3b --- /dev/null +++ b/docs/api/cli/edit.md @@ -0,0 +1,8 @@ +# tmuxp edit - `tmuxp.cli.edit` + +```{eval-rst} +.. automodule:: tmuxp.cli.edit + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/freeze.md b/docs/api/cli/freeze.md new file mode 100644 index 00000000000..70c4d068454 --- /dev/null +++ b/docs/api/cli/freeze.md @@ -0,0 +1,8 @@ +# tmuxp freeze - `tmuxp.cli.freeze` + +```{eval-rst} +.. automodule:: tmuxp.cli.freeze + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/import_config.md b/docs/api/cli/import_config.md new file mode 100644 index 00000000000..3c75e88eadf --- /dev/null +++ b/docs/api/cli/import_config.md @@ -0,0 +1,8 @@ +# tmuxp import - `tmuxp.cli.import_config` + +```{eval-rst} +.. automodule:: tmuxp.cli.import_config + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/index.md b/docs/api/cli/index.md new file mode 100644 index 00000000000..08f49a2131e --- /dev/null +++ b/docs/api/cli/index.md @@ -0,0 +1,30 @@ +(api_cli)= + +# CLI + +:::{warning} +Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions! + +If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues). +::: + +```{toctree} +convert +debug_info +edit +freeze +import_config +load +ls +shell +utils +``` + +## `tmuxp.cli` + +```{eval-rst} +.. automodule:: tmuxp.cli + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/load.md b/docs/api/cli/load.md new file mode 100644 index 00000000000..bae0f6a899f --- /dev/null +++ b/docs/api/cli/load.md @@ -0,0 +1,8 @@ +# tmuxp load - `tmuxp.cli.load` + +```{eval-rst} +.. automodule:: tmuxp.cli.load + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/ls.md b/docs/api/cli/ls.md new file mode 100644 index 00000000000..34d27718a64 --- /dev/null +++ b/docs/api/cli/ls.md @@ -0,0 +1,8 @@ +# tmuxp ls - `tmuxp.cli.ls` + +```{eval-rst} +.. automodule:: tmuxp.cli.ls + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/shell.md b/docs/api/cli/shell.md new file mode 100644 index 00000000000..c6f05d08749 --- /dev/null +++ b/docs/api/cli/shell.md @@ -0,0 +1,8 @@ +# tmuxp shell - `tmuxp.cli.shell` + +```{eval-rst} +.. automodule:: tmuxp.cli.shell + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/cli/utils.md b/docs/api/cli/utils.md new file mode 100644 index 00000000000..4556dcf5342 --- /dev/null +++ b/docs/api/cli/utils.md @@ -0,0 +1,8 @@ +# CLI utilities - `tmuxp.cli.utils` + +```{eval-rst} +.. automodule:: tmuxp.cli.utils + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/exc.md b/docs/api/exc.md new file mode 100644 index 00000000000..70b68a24666 --- /dev/null +++ b/docs/api/exc.md @@ -0,0 +1,8 @@ +# Exceptions - `tmuxp.exc` + +```{eval-rst} +.. automodule:: tmuxp.exc + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 00000000000..89ec3d508b7 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,20 @@ +(api)= + +# API Reference + +:::{seealso} +See {ref}`libtmux's API ` and {ref}`Quickstart ` to see how you can control +tmux via python API calls. +::: + +```{toctree} +internals/index +cli/index +workspace/index +exc +log +plugin +shell +util +types +``` diff --git a/docs/api/internals/config_reader.md b/docs/api/internals/config_reader.md new file mode 100644 index 00000000000..fa932f8643a --- /dev/null +++ b/docs/api/internals/config_reader.md @@ -0,0 +1,14 @@ +# Config reader - `tmuxp._internal.config_reader` + +:::{warning} +Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions! + +If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues). +::: + +```{eval-rst} +.. automodule:: tmuxp._internal.config_reader + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/internals/index.md b/docs/api/internals/index.md new file mode 100644 index 00000000000..74b5fa04816 --- /dev/null +++ b/docs/api/internals/index.md @@ -0,0 +1,14 @@ +(internals)= + +# Internals + +:::{warning} +Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions! + +If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues). +::: + +```{toctree} +config_reader +types +``` diff --git a/docs/api/internals/types.md b/docs/api/internals/types.md new file mode 100644 index 00000000000..f41f12b6d10 --- /dev/null +++ b/docs/api/internals/types.md @@ -0,0 +1,8 @@ +# Typings - `tmuxp._internal.types` + +```{eval-rst} +.. automodule:: tmuxp._internal.types + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/log.md b/docs/api/log.md new file mode 100644 index 00000000000..2e000328c4d --- /dev/null +++ b/docs/api/log.md @@ -0,0 +1,8 @@ +# Logging - `tmuxp.log` + +```{eval-rst} +.. automodule:: tmuxp.log + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/plugin.md b/docs/api/plugin.md new file mode 100644 index 00000000000..fd7ce9781c7 --- /dev/null +++ b/docs/api/plugin.md @@ -0,0 +1,8 @@ +# Plugin - `tmuxp.plugin` + +```{eval-rst} +.. automodule:: tmuxp.plugin + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/shell.md b/docs/api/shell.md new file mode 100644 index 00000000000..286974a67e0 --- /dev/null +++ b/docs/api/shell.md @@ -0,0 +1,8 @@ +# Shell - `tmuxp.shell` + +```{eval-rst} +.. automodule:: tmuxp.shell + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/types.md b/docs/api/types.md new file mode 100644 index 00000000000..adac7ee4d92 --- /dev/null +++ b/docs/api/types.md @@ -0,0 +1,8 @@ +# Typings - `tmuxp.types` + +```{eval-rst} +.. automodule:: tmuxp.types + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/util.md b/docs/api/util.md new file mode 100644 index 00000000000..80e067e169d --- /dev/null +++ b/docs/api/util.md @@ -0,0 +1,8 @@ +# Utilities - `tmuxp.util` + +```{eval-rst} +.. automodule:: tmuxp.util + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/builder.md b/docs/api/workspace/builder.md new file mode 100644 index 00000000000..24525e1efbc --- /dev/null +++ b/docs/api/workspace/builder.md @@ -0,0 +1,8 @@ +# Builder - `tmuxp.workspace.builder` + +```{eval-rst} +.. automodule:: tmuxp.workspace.builder + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/constants.md b/docs/api/workspace/constants.md new file mode 100644 index 00000000000..df8cf583f21 --- /dev/null +++ b/docs/api/workspace/constants.md @@ -0,0 +1,8 @@ +# Constants - `tmuxp.workspace.constants` + +```{eval-rst} +.. automodule:: tmuxp.workspace.constants + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/finders.md b/docs/api/workspace/finders.md new file mode 100644 index 00000000000..d48318c361e --- /dev/null +++ b/docs/api/workspace/finders.md @@ -0,0 +1,8 @@ +# Finders - `tmuxp.workspace.finders` + +```{eval-rst} +.. automodule:: tmuxp.workspace.finders + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/freezer.md b/docs/api/workspace/freezer.md new file mode 100644 index 00000000000..ec9afd873ac --- /dev/null +++ b/docs/api/workspace/freezer.md @@ -0,0 +1,8 @@ +# Freezer - `tmuxp.workspace.freezer` + +```{eval-rst} +.. automodule:: tmuxp.workspace.freezer + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/importers.md b/docs/api/workspace/importers.md new file mode 100644 index 00000000000..b3b9cd00db2 --- /dev/null +++ b/docs/api/workspace/importers.md @@ -0,0 +1,8 @@ +# Importers - `tmuxp.workspace.importers` + +```{eval-rst} +.. automodule:: tmuxp.workspace.importers + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/index.md b/docs/api/workspace/index.md new file mode 100644 index 00000000000..4c2d6241add --- /dev/null +++ b/docs/api/workspace/index.md @@ -0,0 +1,19 @@ +(workspace)= + +# Workspace + +:::{warning} +Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions! + +If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues). +::: + +```{toctree} +builder +constants +finders +freezer +importers +loader +validation +``` diff --git a/docs/api/workspace/loader.md b/docs/api/workspace/loader.md new file mode 100644 index 00000000000..f422644ab04 --- /dev/null +++ b/docs/api/workspace/loader.md @@ -0,0 +1,8 @@ +# Loader - `tmuxp.workspace.loader` + +```{eval-rst} +.. automodule:: tmuxp.workspace.loader + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/api/workspace/validation.md b/docs/api/workspace/validation.md new file mode 100644 index 00000000000..77f7655e801 --- /dev/null +++ b/docs/api/workspace/validation.md @@ -0,0 +1,8 @@ +# Validation - `tmuxp.workspace.validation` + +```{eval-rst} +.. automodule:: tmuxp.workspace.validation + :members: + :show-inheritance: + :undoc-members: +``` diff --git a/docs/index.md b/docs/index.md index 93882dd1f84..14b69dedb04 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,7 +32,7 @@ plugins/index :hidden: developing -api +api/index history migration about_tmux diff --git a/docs/redirects.txt b/docs/redirects.txt index 31f280ec092..66d2cb860b4 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -1,4 +1,5 @@ "cli.md" "commands/index.md" +"api.md" "api/index.md" "examples.md" "configuration/examples.md" "plugin_system.md" "plugins/index.md" "commands/index.md" "cli/index.md" diff --git a/src/tmuxp/__init__.py b/src/tmuxp/__init__.py index 1d0c36959fe..1ff777e9679 100644 --- a/src/tmuxp/__init__.py +++ b/src/tmuxp/__init__.py @@ -1,12 +1,8 @@ # flake8: NOQA: F401 """tmux session manager. -tmuxp -~~~~~ - :copyright: Copyright 2013- Tony Narlock. :license: MIT, see LICENSE for details - """ from . import cli, util from .__about__ import ( diff --git a/src/tmuxp/cli/import_config.py b/src/tmuxp/cli/import_config.py index 8bab8d918a8..4a0eb99cabc 100644 --- a/src/tmuxp/cli/import_config.py +++ b/src/tmuxp/cli/import_config.py @@ -24,7 +24,7 @@ def get_tmuxinator_dir() -> pathlib.Path: See Also -------- - :meth:`tmuxp.workspace.importers.tmuxinator.import_tmuxinator` + :meth:`tmuxp.workspace.importers.import_tmuxinator` """ if "TMUXINATOR_CONFIG" in os.environ: return pathlib.Path(os.environ["TMUXINATOR_CONFIG"]).expanduser() @@ -42,7 +42,7 @@ def get_teamocil_dir() -> pathlib.Path: See Also -------- - :meth:`tmuxp.workspace.importers.teamocil.import_teamocil` + :meth:`tmuxp.workspace.importers.import_teamocil` """ return pathlib.Path("~/.teamocil/").expanduser() diff --git a/src/tmuxp/cli/utils.py b/src/tmuxp/cli/utils.py index 4dc861cf6be..b516555186b 100644 --- a/src/tmuxp/cli/utils.py +++ b/src/tmuxp/cli/utils.py @@ -40,8 +40,10 @@ def prompt( Parameters ---------- - :param name: prompt text - :param default: default value if no input provided. + name : + prompt text + default : + default value if no input provided. Returns ------- @@ -49,12 +51,9 @@ def prompt( See Also -------- - :meth:`~prompt`, :meth:`~prompt_bool` and :meth:`prompt_choices` are from - `flask-script`_. See the `flask-script license`_. - - .. _flask-script: https://github.com/techniq/flask-script - .. _flask-script license: - https://github.com/techniq/flask-script/blob/master/LICENSE + :meth:`~prompt`, :meth:`~prompt_bool` and :meth:`~prompt_choices` are from + `flask-script `_. See the + `flask-script license `_. """ _prompt = name + (default and " [%s]" % default or "") _prompt += name.endswith("?") and " " or ": " @@ -83,10 +82,14 @@ def prompt_bool( Parameters ---------- - :param name: prompt text - :param default: default value if no input provided. - :param yes_choices: default 'y', 'yes', '1', 'on', 'true', 't' - :param no_choices: default 'n', 'no', '0', 'off', 'false', 'f' + name : + prompt text + default : + default value if no input provided. + yes_choices : + default 'y', 'yes', '1', 'on', 'true', 't' + no_choices : + default 'n', 'no', '0', 'off', 'false', 'f' Returns ------- @@ -130,11 +133,15 @@ def prompt_choices( Parameters ---------- - :param name: prompt text - :param choices: list or tuple of available choices. Choices may be - single strings or (key, value) tuples. - :param default: default value if no input provided. - :param no_choice: acceptable list of strings for "null choice" + name : + prompt text + choices : + list or tuple of available choices. Choices may be single strings or + (key, value) tuples. + default : + default value if no input provided. + no_choice : + acceptable list of strings for "null choice" Returns ------- @@ -274,6 +281,6 @@ def unstyle(text: str) -> str: Credit: click. - :param text: the text to remove style information from. + text : the text to remove style information from. """ return strip_ansi(text) diff --git a/src/tmuxp/exc.py b/src/tmuxp/exc.py index eff64bc4197..3b77c5a64d6 100644 --- a/src/tmuxp/exc.py +++ b/src/tmuxp/exc.py @@ -1,9 +1,4 @@ -"""Exceptions for tmuxp. - -tmuxp.exc -~~~~~~~~~ - -""" +"""Exceptions for tmuxp.""" import typing as t from libtmux._internal.query_list import ObjectDoesNotExist diff --git a/src/tmuxp/log.py b/src/tmuxp/log.py index 62baacf0d29..d98b860ce96 100644 --- a/src/tmuxp/log.py +++ b/src/tmuxp/log.py @@ -1,10 +1,5 @@ #!/usr/bin/env python -"""Log utilities for tmuxp. - -tmuxp.log -~~~~~~~~~ - -""" +"""Log utilities for tmuxp.""" import logging import time import typing as t diff --git a/src/tmuxp/shell.py b/src/tmuxp/shell.py index 946eca37cf7..183fbf14104 100644 --- a/src/tmuxp/shell.py +++ b/src/tmuxp/shell.py @@ -1,9 +1,4 @@ -"""Utility and helper methods for tmuxp. - -tmuxp.shell -~~~~~~~~~~~ - -""" +"""Utility and helper methods for tmuxp.""" import logging import os import pathlib diff --git a/src/tmuxp/util.py b/src/tmuxp/util.py index 888f8f551d1..2d8fdd845c6 100644 --- a/src/tmuxp/util.py +++ b/src/tmuxp/util.py @@ -1,9 +1,4 @@ -"""Utility and helper methods for tmuxp. - -tmuxp.util -~~~~~~~~~~ - -""" +"""Utility and helper methods for tmuxp.""" import logging import os import pathlib diff --git a/src/tmuxp/workspace/builder.py b/src/tmuxp/workspace/builder.py index 0efa22f1502..529dc6888ad 100644 --- a/src/tmuxp/workspace/builder.py +++ b/src/tmuxp/workspace/builder.py @@ -1,9 +1,4 @@ -"""Create a tmux workspace from a workspace :py:obj:`dict`. - -tmuxp.workspace.builder -~~~~~~~~~~~~~~~~~~~~~~~ - -""" +"""Create a tmux workspace from a workspace :py:obj:`dict`.""" import logging import time import typing as t diff --git a/src/tmuxp/workspace/loader.py b/src/tmuxp/workspace/loader.py index e7880ecc0e6..e44984687c1 100644 --- a/src/tmuxp/workspace/loader.py +++ b/src/tmuxp/workspace/loader.py @@ -1,9 +1,4 @@ -"""Workspace hydration and loading for tmuxp. - -tmuxp.workspace.loader -~~~~~~~~~~~~~~~~~~~~~~ - -""" +"""Workspace hydration and loading for tmuxp.""" import logging import os import pathlib