diff --git a/docs/migration.md b/docs/migration.md index 7bd3f466..88016ebe 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,6 +1,6 @@ (migration)= -```{currentmodule} libtmux +```{currentmodule} libvcs ``` diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 22aeb435..1e3f2ee9 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -2,11 +2,11 @@ # `pytest` Plugin -With libvcs's pytest plugin for [pytest], you can easily create Git, SVN, and Mercurial repositories on the fly. +With libvcs's pytest plugin for [pytest], you can easily create Git, Subversion (SVN), and Mercurial repositories on the fly. ```{seealso} Are you using libvcs? -Looking for more flexibility, correctness, or power? Need different defaults? [Connect with us] on GitHub. We'd love to hear about your use case—APIs won't be stabilized until we're confident everything meets expectations. +Looking for more flexibility, correctness, or power? Need different defaults? [Connect with us] on GitHub. We'd love to hear about your use case. Our APIs won't be stabilized until we're confident they meet all expectations. [connect with us]: https://github.com/vcs-python/libvcs/discussions ``` @@ -22,14 +22,14 @@ Looking for more flexibility, correctness, or power? Need different defaults? [C Install `libvcs` using your preferred Python package manager: ```console -$ pip install libvcs +$ python -m pip install libvcs ``` -Pytest will automatically detect the plugin, and its fixtures will be available. +Once installed, pytest will automatically detect the plugin and make its fixtures available. ## Fixtures -This pytest plugin works by providing {ref}`pytest fixtures `. The plugin's fixtures ensure that a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache initial repositories, improving performance across tests. +This pytest plugin provides {ref}`pytest fixtures ` that ensure a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache the initial repositories, improving performance across tests. [session-scoped fixtures]: https://docs.pytest.org/en/8.3.x/how-to/fixtures.html#fixture-scopes @@ -37,26 +37,26 @@ This pytest plugin works by providing {ref}`pytest fixtures `_): {func}`vcs_user` - - For git only: {func}`git_commit_envvars` + - User (e.g., _`user `_): {func}`vcs_user` + - Git-specific: {func}`git_commit_envvars` -These ensure that repositories can be cloned and created without unnecessary warnings. +These fixtures ensure that repositories can be cloned and created without unnecessary warnings. [`HGRCPATH`]: https://www.mercurial-scm.org/doc/hg.1.html#:~:text=UNIX%2Dlike%20environments.-,HGRCPATH,-If%20not%20set [`GIT_CONFIG`]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIG @@ -65,17 +65,18 @@ These ensure that repositories can be cloned and created without unnecessary war To configure the above fixtures with `autouse=True`, add them to your `conftest.py` file or test file, depending on the desired scope. -_Why aren't these fixtures added automatically by the plugin?_ This design choice promotes explicitness, adhering to best practices for pytest plugins and Python packages. +_Why aren't these fixtures added automatically by the plugin?_ This design choice promotes explicitness and adheres to best practices for pytest plugins and Python packages. ### Setting a Temporary Home Directory -To set a temporary home directory, use the {func}`set_home` fixture with `autouse=True`: +To set up a temporary home directory, use the {func}`set_home` fixture with `autouse=True`: ```python import pytest @pytest.fixture(autouse=True) -def setup(set_home: None): +def setup_home(set_home: None) -> None: + """Configure a temporary home directory for testing.""" pass ``` @@ -83,12 +84,13 @@ def setup(set_home: None): #### Git -You can override the default author used in {func}`git_remote_repo` and other -fixtures via {func}`vcs_name`, {func}`vcs_email`, and {func}`vcs_user`: +You can override the default author information used in {func}`git_remote_repo` and other +fixtures by customizing {func}`vcs_name`, {func}`vcs_email`, or {func}`vcs_user`: -``` +```python @pytest.fixture(scope="session") def vcs_name() -> str: + """Provide a custom author name for Git commits.""" return "My custom name" ``` @@ -98,23 +100,29 @@ Use the {func}`set_gitconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup(set_gitconfig: None): +def setup_git(set_gitconfig: None) -> None: + """Configure Git settings for testing.""" pass ``` -Sometimes, `set_getconfig` via `GIT_CONFIG` doesn't apply as expected. For those +Sometimes, `set_gitconfig` via `GIT_CONFIG` doesn't apply as expected. For those cases, you can use {func}`git_commit_envvars`: ```python import pytest +from typing import Dict, Any +from libvcs.pytest_plugin import CreateRepoPytestFixtureFn, git_remote_repo_single_commit_post_init @pytest.fixture def my_git_repo( create_git_remote_repo: CreateRepoPytestFixtureFn, gitconfig: pathlib.Path, - git_commit_envvars: "_ENV", + git_commit_envvars: Dict[str, Any], ) -> pathlib.Path: - """Copy the session-scoped Git repository to a temporary directory.""" + """Create a fresh Git repository in a temporary directory. + + This fixture demonstrates how to create a Git repository with custom commit settings. + """ repo_path = create_git_remote_repo() git_remote_repo_single_commit_post_init( remote_repo_path=repo_path, @@ -123,6 +131,10 @@ def my_git_repo( return repo_path ``` +```{note} +The `create_git_remote_repo` fixture creates a repository once per test session and reuses it, making copies for individual tests to avoid repeated `git init` operations. +``` + #### Mercurial Use the {func}`set_hgconfig` fixture with `autouse=True`: @@ -131,13 +143,14 @@ Use the {func}`set_hgconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup(set_hgconfig: None): +def setup_hg(set_hgconfig: None) -> None: + """Configure Mercurial settings for testing.""" pass ``` ## Examples -For usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests). +For more usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests). ## API Reference diff --git a/docs/quickstart.md b/docs/quickstart.md index e9508b34..63d7b4f5 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,38 +4,38 @@ ## Installation -For latest official version: +For the latest official version: ```console -$ pip install --user libvcs +$ python -m pip install libvcs ``` -Upgrading: +Upgrading to the latest version: ```console -$ pip install --user --upgrade libvcs +$ python -m pip install --upgrade libvcs ``` (developmental-releases)= ### Developmental releases -New versions of libvcs are published to PyPI as alpha, beta, or release candidates. In their -versions you will see notification like `a1`, `b1`, and `rc1`, respectively. `1.10.0b4` would mean -the 4th beta release of `1.10.0` before general availability. +New versions of libvcs are published to PyPI as alpha, beta, or release candidates. These versions +are marked with notations like `a1`, `b1`, and `rc1`, respectively. For example, `1.10.0b4` indicates +the 4th beta release of version `1.10.0` before its general availability. -- [pip]\: +Installation options: + +- Via pip (pre-release versions): ```console - $ pip install --user --upgrade --pre libvcs + $ python -m pip install --upgrade --pre libvcs ``` -via trunk (can break easily): - -- [pip]\: +- Via trunk (development version, may be unstable): ```console - $ pip install --user -e git+https://github.com/vcs-python/libvcs.git#egg=libvcs + $ python -m pip install -e git+https://github.com/vcs-python/libvcs.git#egg=libvcs ``` [pip]: https://pip.pypa.io/en/stable/