docs: Adopt doc-pytest-plugin for pytest plugin page (#520)

Replaces the hand-authored pytest plugin page with the shared
`doc-pytest-plugin` directive from `sphinx-autodoc-pytest-fixtures`.
The generated page provides a consistent install block, `pytest11`
autodiscovery note, fixture summary table, and full fixture reference
— maintained automatically as fixtures change.

- **docs/api/pytest-plugin.md** — rewritten around `doc-pytest-plugin`
  with project-specific prose in the body
- **docs/conf.py** — enables `sphinx_autodoc_pytest_fixtures` extension
  and adds `pytest-plugin` to the API toctree
- **pyproject.toml** — bumps `gp-sphinx` and
  `sphinx-autodoc-pytest-fixtures` to `0.0.1a2`

Author: tony

docs/api/index.md

@@ -37,7 +37,7 @@ One call to fetch or create a working copy.
 :::
 
 :::{grid-item-card} pytest Plugin
-:link: api/pytest-plugin
+:link: /api/pytest-plugin
 :link-type: doc
 Session-scoped fixtures for Git, SVN, and Mercurial
 repositories. Drop-in test isolation.

docs/api/pytest-plugin.md

@@ -2,146 +2,42 @@
 
 # `pytest` Plugin
 
-With libvcs's pytest plugin for [pytest], you can easily create Git, SVN, and Mercurial repositories on the fly.
+:::{doc-pytest-plugin} libvcs.pytest_plugin
+:project: libvcs
+:package: libvcs
+:summary: libvcs ships a pytest plugin for creating isolated Git, Mercurial, and Subversion repositories during tests.
+:tests-url: https://github.com/vcs-python/libvcs/tree/master/tests
 
-```{seealso} Are you using libvcs?
+Use these fixtures when your tests need disposable repositories, config files,
+and home-directory setup without repeating bootstrap code in every suite.
 
-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.
+## Recommended fixtures
 
-[connect with us]: https://github.com/vcs-python/libvcs/discussions
-```
-
-[pytest]: https://docs.pytest.org/
-
-## Usage
-
-Install `libvcs` using your preferred Python package manager:
-
-```console
-$ pip install libvcs
-```
-
-Pytest will automatically detect the plugin, and its fixtures will be available.
-
-## Fixtures
-
-This pytest plugin works by providing [pytest fixtures](https://docs.pytest.org/en/stable/how-to/fixtures.html). 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.
-
-[session-scoped fixtures]: https://docs.pytest.org/en/8.3.x/how-to/fixtures.html#fixture-scopes
-
-(recommended-fixtures)=
-
-## Recommended Fixtures
-
-When the plugin is enabled and `pytest` is run, these overridable fixtures are automatically used:
+These fixtures are the usual starting point when enabling the plugin:
 
-- Create temporary test directories for:
-  - `/home/` ({func}`home_path`)
-  - `/home/${user}` ({func}`user_path`)
-- Set the home directory:
-  - Patch `$HOME` to point to {func}`user_path` using ({func}`set_home`)
-- Create configuration files:
-  - `.gitconfig` via {func}`gitconfig`
-  - `.hgrc` via {func}`hgconfig`
-- Set default VCS configurations:
-  - Use {func}`hgconfig` for [`HGRCPATH`] via {func}`set_hgconfig`
-  - Use {func}`gitconfig` for [`GIT_CONFIG`] via {func}`set_gitconfig`
-- Set default commit names and emails:
-  - Name: {func}`vcs_name`
-  - Email: {func}`vcs_email`
-  - User (e.g. _`user <email@tld>`_): {func}`vcs_user`
-  - For git only: {func}`git_commit_envvars`
+- {fixture}`set_home` patches `$HOME` to point at {fixture}`user_path`.
+- {fixture}`set_gitconfig` and {fixture}`set_hgconfig` apply stable VCS
+  configuration.
+- {fixture}`vcs_name`, {fixture}`vcs_email`, and {fixture}`vcs_user` let you
+  override commit identity defaults.
+- {fixture}`git_commit_envvars` helps when Git ignores `GIT_CONFIG` in a
+  subprocess-heavy test.
 
-These ensure that repositories can be cloned and created without unnecessary warnings.
+## Bootstrapping in `conftest.py`
 
-[`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
-
-## Bootstrapping pytest in `conftest.py`
-
-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.
-
-### Setting a Temporary Home Directory
-
-To set a temporary home directory, use the {func}`set_home` fixture with `autouse=True`:
+Keep autouse setup explicit in your own `conftest.py` instead of having the
+plugin force global side effects.
 
 ```python
 import pytest
 
-@pytest.fixture(autouse=True)
-def setup(set_home: None):
-    pass
-```
-
-### VCS Configuration
-
-#### 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`:
-
-```
-@pytest.fixture(scope="session")
-def vcs_name() -> str:
-    return "My custom name"
-```
-
-Use the {func}`set_gitconfig` fixture with `autouse=True`:
-
-```python
-import pytest
 
 @pytest.fixture(autouse=True)
-def setup(set_gitconfig: None):
+def setup(
+    set_home: None,
+    set_gitconfig: None,
+    set_hgconfig: None,
+) -> None:
     pass
 ```
-
-Sometimes, `set_getconfig` via `GIT_CONFIG` doesn't apply as expected. For those
-cases, you can use {func}`git_commit_envvars`:
-
-```python
-import pytest
-
-@pytest.fixture
-def my_git_repo(
-    create_git_remote_repo: CreateRepoPytestFixtureFn,
-    gitconfig: pathlib.Path,
-    git_commit_envvars: "_ENV",
-) -> pathlib.Path:
-    """Copy the session-scoped Git repository to a temporary directory."""
-    repo_path = create_git_remote_repo()
-    git_remote_repo_single_commit_post_init(
-        remote_repo_path=repo_path,
-        env=git_commit_envvars,
-    )
-    return repo_path
-```
-
-#### Mercurial
-
-Use the {func}`set_hgconfig` fixture with `autouse=True`:
-
-```python
-import pytest
-
-@pytest.fixture(autouse=True)
-def setup(set_hgconfig: None):
-    pass
-```
-
-## Examples
-
-For usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests).
-
-## API Reference
-
-```{eval-rst}
-.. automodule:: libvcs.pytest_plugin
-    :members:
-    :inherited-members:
-    :private-members:
-    :show-inheritance:
-    :member-order: bysource
-```
+:::

docs/conf.py

@@ -30,7 +30,10 @@
     source_branch="master",
     light_logo="img/libvcs.svg",
     dark_logo="img/libvcs-dark.svg",
-    extra_extensions=["sphinx.ext.todo"],
+    extra_extensions=[
+        "sphinx.ext.todo",
+        "sphinx_autodoc_pytest_fixtures",
+    ],
     intersphinx_mapping={
         "py": ("https://docs.python.org/3", None),
         "pip": ("https://pip.pypa.io/en/latest/", None),

docs/index.md

@@ -34,7 +34,7 @@ Clone and update local repositories.
 :::
 
 :::{grid-item-card} pytest Plugin
-:link: api/pytest-plugin
+:link: /api/pytest-plugin
 :link-type: doc
 Fixtures for isolated VCS test repos.
 :::
@@ -88,7 +88,7 @@ updates a local checkout in one call.
 
 ## Testing
 
-libvcs ships a [pytest plugin](api/pytest-plugin.md) with
+libvcs ships a [pytest plugin](/api/pytest-plugin/) with
 session-scoped fixtures for Git, SVN, and Mercurial repositories:
 
 ```python

pyproject.toml

@@ -64,7 +64,8 @@ Changes = "https://github.com/vcs-python/libvcs/blob/master/CHANGES"
 [dependency-groups]
 dev = [
   # Docs
-  "gp-sphinx==0.0.1a1",
+  "gp-sphinx==0.0.1a2",
+  "sphinx-autodoc-pytest-fixtures==0.0.1a2",
   "gp-libs",
   "sphinx-autobuild",
   # Testing
@@ -83,7 +84,8 @@ dev = [
 ]
 
 docs = [
-  "gp-sphinx==0.0.1a1",
+  "gp-sphinx==0.0.1a2",
+  "sphinx-autodoc-pytest-fixtures==0.0.1a2",
   "gp-libs",
   "sphinx-autobuild",
 ]