docs(redesign): restructure documentation to Library Skeleton pattern

docs/api/index.md

@@ -0,0 +1,55 @@
+(api)=
+
+(reference)=
+
+# API Reference
+
+libvcs exposes three public subsystems -- URL parsing, command execution,
+and repository synchronization -- plus a pytest plugin for test fixtures.
+
+All APIs are pre-1.0 and may change between minor versions.
+Pin to a range: `libvcs>=0.39,<0.40`.
+
+## Subsystems
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} URL Parsing
+:link: /url/index
+:link-type: doc
+Detect, validate, and normalize Git / Hg / SVN URLs.
+Typed dataclasses with pip- and npm-style support.
+:::
+
+:::{grid-item-card} Commands
+:link: /cmd/index
+:link-type: doc
+Thin Python wrappers around `git`, `hg`, and `svn` CLIs.
+Fine-grained control over individual VCS operations.
+:::
+
+:::{grid-item-card} Sync
+:link: /sync/index
+:link-type: doc
+High-level clone-and-update for local repositories.
+One call to fetch or create a working copy.
+:::
+
+:::{grid-item-card} pytest Plugin
+:link: api/pytest-plugin
+:link-type: doc
+Session-scoped fixtures for Git, SVN, and Mercurial
+repositories. Drop-in test isolation.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+/url/index
+/cmd/index
+/sync/index
+pytest-plugin
+```

docs/cmd/index.md

@@ -28,8 +28,33 @@ The `libvcs.cmd` module provides Python wrappers for VCS command-line tools:
 | `libvcs.cmd` | Fine-grained control over individual VCS commands |
 | `libvcs.sync` | High-level repository cloning and updating |
 
+## Modules
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Git
+:link: git/index
+:link-type: doc
+Full git CLI wrapper with sub-command managers (branch, remote, stash, ...).
+:::
+
+:::{grid-item-card} Mercurial
+:link: hg
+:link-type: doc
+Mercurial CLI wrapper.
+:::
+
+:::{grid-item-card} Subversion
+:link: svn
+:link-type: doc
+Subversion CLI wrapper.
+:::
+
+::::
+
 ```{toctree}
-:caption: API
+:hidden:
 
 git/index
 hg

docs/conf.py

@@ -41,8 +41,10 @@
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
     "myst_parser",
+    "sphinx_design",
     "linkify_issues",
 ]
+myst_heading_anchors = 4
 myst_enable_extensions = [
     "colon_fence",
     "substitution",

docs/index.md

@@ -2,30 +2,109 @@
 
 # libvcs
 
-```{include} ../README.md
-:start-after: </div>
+Typed Python utilities for Git, SVN, and Mercurial. Parse URLs,
+execute commands, and synchronize repositories -- all with a
+consistent, type-friendly API.
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and parse your first VCS URL in 5 minutes.
+:::
+
+:::{grid-item-card} URL Parsing
+:link: url/index
+:link-type: doc
+Parse, validate, and normalize git/hg/svn URLs.
+:::
+
+:::{grid-item-card} Commands
+:link: cmd/index
+:link-type: doc
+Typed wrappers for git, hg, and svn CLI operations.
+:::
+
+:::{grid-item-card} Sync
+:link: sync/index
+:link-type: doc
+Clone and update local repositories.
+:::
+
+:::{grid-item-card} pytest Plugin
+:link: api/pytest-plugin
+:link-type: doc
+Fixtures for isolated VCS test repos.
+:::
+
+:::{grid-item-card} Project
+:link: project/index
+:link-type: doc
+Contributing, code style, release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ pip install libvcs
 ```
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+```console
+$ uv add libvcs
+```
 
-quickstart
-topics/index
-url/index
-cmd/index
-sync/index
-pytest-plugin
+```{tip}
+libvcs is pre-1.0. Pin to a range: `libvcs>=0.39,<0.40`
+```
+
+See [Quickstart](quickstart.md) for all methods and first steps.
+
+## At a glance
+
+```python
+from libvcs.url.git import GitURL
+
+url = GitURL(url="git@github.com:vcs-python/libvcs.git")
+url.hostname  # 'github.com'
+url.path      # 'vcs-python/libvcs'
+
+GitURL.is_valid(url="https://github.com/vcs-python/libvcs.git")
+# True
+```
+
+libvcs gives you typed dataclasses for every parsed URL, thin CLI
+wrappers for `git` / `hg` / `svn`, and high-level sync that clones or
+updates a local checkout in one call.
+
+| Layer | Module | Purpose |
+|-------|--------|---------|
+| URL parsing | {mod}`libvcs.url` | Detect, validate, normalize VCS URLs |
+| Commands | {mod}`libvcs.cmd` | Execute individual VCS CLI operations |
+| Sync | {mod}`libvcs.sync` | Clone and update local repositories |
+
+## Testing
+
+libvcs ships a [pytest plugin](api/pytest-plugin.md) with
+session-scoped fixtures for Git, SVN, and Mercurial repositories:
+
+```python
+def test_my_tool(create_git_remote_repo):
+    repo_path = create_git_remote_repo()
+    assert repo_path.exists()
 ```
 
 ```{toctree}
-:caption: Project
 :hidden:
 
-contributing/index
+quickstart
+topics/index
+api/index
 internals/index
+project/index
 history
 migration
-GitHub <https://github.com/vcs-python/libvcs>
-
 ```

docs/internals/index.md

@@ -8,7 +8,56 @@ Be careful with these! Internal APIs are **not** covered by version policies. Th
 If you need an internal API stabilized please [file an issue](https://github.com/vcs-python/libvcs/issues).
 :::
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Exceptions
+:link: exc
+:link-type: doc
+Error hierarchy for VCS operations.
+:::
+
+:::{grid-item-card} Types
+:link: types
+:link-type: doc
+Shared type aliases and protocols.
+:::
+
+:::{grid-item-card} Dataclasses
+:link: dataclasses
+:link-type: doc
+Internal dataclass utilities.
+:::
+
+:::{grid-item-card} QueryList
+:link: query_list
+:link-type: doc
+Filterable list for object collections.
+:::
+
+:::{grid-item-card} Run
+:link: run
+:link-type: doc
+Runtime helpers and environment utilities.
+:::
+
+:::{grid-item-card} Subprocess
+:link: subprocess
+:link-type: doc
+Subprocess wrappers for VCS binaries.
+:::
+
+:::{grid-item-card} Shortcuts
+:link: shortcuts
+:link-type: doc
+Convenience functions for common operations.
+:::
+
+::::
+
 ```{toctree}
+:hidden:
+
 exc
 types
 dataclasses

docs/project/code-style.md

@@ -0,0 +1,54 @@
+(code-style)=
+
+# Code Style
+
+## Formatting and linting
+
+libvcs uses [ruff](https://ruff.rs) for formatting **and** linting in a
+single tool. The full rule set is declared in `pyproject.toml` under
+`[tool.ruff]`.
+
+```console
+$ uv run ruff format .
+```
+
+```console
+$ uv run ruff check . --fix --show-fixes
+```
+
+## Type checking
+
+[mypy](http://mypy-lang.org/) runs in strict mode:
+
+```console
+$ uv run mypy src tests
+```
+
+## Docstrings
+
+All public APIs use **NumPy-style** docstrings:
+
+```python
+def fetch(url: str, *, branch: str | None = None) -> str:
+    """Fetch a remote branch.
+
+    Parameters
+    ----------
+    url : str
+        Repository URL.
+    branch : str or None
+        Branch name. ``None`` means the default branch.
+
+    Returns
+    -------
+    str
+        The fetched commit hash.
+    """
+```
+
+## Imports
+
+- `from __future__ import annotations` at the top of every file.
+- Standard-library modules use **namespace imports**: `import pathlib`,
+  not `from pathlib import Path`.
+- Typing: `import typing as t`, then `t.Optional`, `t.Any`, etc.

docs/project/contributing.md

@@ -0,0 +1,10 @@
+(contributing)=
+
+(developing)=
+
+# Contributing
+
+As an open source project, libvcs accepts contributions through GitHub.
+
+Ready to dive in? See the [Development Workflow](workflow.md) for
+environment setup, running tests, linting, and building docs.