Skip to content

Commit 1fe79cc

Browse files
tonytony
authored
Merge pull request #518 from vcs-python/doc-redesign-spring-2026
docs(redesign): restructure documentation to Library Skeleton pattern
2 parents 54977ea + c59ecee commit 1fe79cc

File tree

18 files changed

+526
-44
lines changed

18 files changed

+526
-44
lines changed

‎docs/api/index.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
(api)=
2+
3+
(reference)=
4+
5+
# API Reference
6+
7+
libvcs exposes three public subsystems -- URL parsing, command execution,
8+
and repository synchronization -- plus a pytest plugin for test fixtures.
9+
10+
All APIs are pre-1.0 and may change between minor versions.
11+
Pin to a range: `libvcs>=0.39,<0.40`.
12+
13+
## Subsystems
14+
15+
::::{grid} 1 1 2 2
16+
:gutter: 2 2 3 3
17+
18+
:::{grid-item-card} URL Parsing
19+
:link: /url/index
20+
:link-type: doc
21+
Detect, validate, and normalize Git / Hg / SVN URLs.
22+
Typed dataclasses with pip- and npm-style support.
23+
:::
24+
25+
:::{grid-item-card} Commands
26+
:link: /cmd/index
27+
:link-type: doc
28+
Thin Python wrappers around `git`, `hg`, and `svn` CLIs.
29+
Fine-grained control over individual VCS operations.
30+
:::
31+
32+
:::{grid-item-card} Sync
33+
:link: /sync/index
34+
:link-type: doc
35+
High-level clone-and-update for local repositories.
36+
One call to fetch or create a working copy.
37+
:::
38+
39+
:::{grid-item-card} pytest Plugin
40+
:link: api/pytest-plugin
41+
:link-type: doc
42+
Session-scoped fixtures for Git, SVN, and Mercurial
43+
repositories. Drop-in test isolation.
44+
:::
45+
46+
::::
47+
48+
```{toctree}
49+
:hidden:
50+
51+
/url/index
52+
/cmd/index
53+
/sync/index
54+
pytest-plugin
55+
```

docs/pytest-plugin.md renamed to docs/api/pytest-plugin.md

File renamed without changes.

‎docs/cmd/index.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,33 @@ The `libvcs.cmd` module provides Python wrappers for VCS command-line tools:
2828
| `libvcs.cmd` | Fine-grained control over individual VCS commands |
2929
| `libvcs.sync` | High-level repository cloning and updating |
3030

31+
## Modules
32+
33+
::::{grid} 1 1 2 2
34+
:gutter: 2 2 3 3
35+
36+
:::{grid-item-card} Git
37+
:link: git/index
38+
:link-type: doc
39+
Full git CLI wrapper with sub-command managers (branch, remote, stash, ...).
40+
:::
41+
42+
:::{grid-item-card} Mercurial
43+
:link: hg
44+
:link-type: doc
45+
Mercurial CLI wrapper.
46+
:::
47+
48+
:::{grid-item-card} Subversion
49+
:link: svn
50+
:link-type: doc
51+
Subversion CLI wrapper.
52+
:::
53+
54+
::::
55+
3156
```{toctree}
32-
:caption: API
57+
:hidden:
3358
3459
git/index
3560
hg

‎docs/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,10 @@
4141
"sphinxext.opengraph",
4242
"sphinxext.rediraffe",
4343
"myst_parser",
44+
"sphinx_design",
4445
"linkify_issues",
4546
]
47+
myst_heading_anchors = 4
4648
myst_enable_extensions = [
4749
"colon_fence",
4850
"substitution",

‎docs/contributing/index.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎docs/index.md‎

Lines changed: 94 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,109 @@
22

33
# libvcs
44

5-
```{include} ../README.md
6-
:start-after: </div>
5+
Typed Python utilities for Git, SVN, and Mercurial. Parse URLs,
6+
execute commands, and synchronize repositories -- all with a
7+
consistent, type-friendly API.
8+
9+
::::{grid} 1 2 3 3
10+
:gutter: 2 2 3 3
11+
12+
:::{grid-item-card} Quickstart
13+
:link: quickstart
14+
:link-type: doc
15+
Install and parse your first VCS URL in 5 minutes.
16+
:::
17+
18+
:::{grid-item-card} URL Parsing
19+
:link: url/index
20+
:link-type: doc
21+
Parse, validate, and normalize git/hg/svn URLs.
22+
:::
23+
24+
:::{grid-item-card} Commands
25+
:link: cmd/index
26+
:link-type: doc
27+
Typed wrappers for git, hg, and svn CLI operations.
28+
:::
29+
30+
:::{grid-item-card} Sync
31+
:link: sync/index
32+
:link-type: doc
33+
Clone and update local repositories.
34+
:::
35+
36+
:::{grid-item-card} pytest Plugin
37+
:link: api/pytest-plugin
38+
:link-type: doc
39+
Fixtures for isolated VCS test repos.
40+
:::
41+
42+
:::{grid-item-card} Project
43+
:link: project/index
44+
:link-type: doc
45+
Contributing, code style, release process.
46+
:::
47+
48+
::::
49+
50+
## Install
51+
52+
```console
53+
$ pip install libvcs
754
```
855

9-
```{toctree}
10-
:maxdepth: 2
11-
:hidden:
56+
```console
57+
$ uv add libvcs
58+
```
1259

13-
quickstart
14-
topics/index
15-
url/index
16-
cmd/index
17-
sync/index
18-
pytest-plugin
60+
```{tip}
61+
libvcs is pre-1.0. Pin to a range: `libvcs>=0.39,<0.40`
62+
```
63+
64+
See [Quickstart](quickstart.md) for all methods and first steps.
65+
66+
## At a glance
67+
68+
```python
69+
from libvcs.url.git import GitURL
70+
71+
url = GitURL(url="git@github.com:vcs-python/libvcs.git")
72+
url.hostname # 'github.com'
73+
url.path # 'vcs-python/libvcs'
74+
75+
GitURL.is_valid(url="https://github.com/vcs-python/libvcs.git")
76+
# True
77+
```
78+
79+
libvcs gives you typed dataclasses for every parsed URL, thin CLI
80+
wrappers for `git` / `hg` / `svn`, and high-level sync that clones or
81+
updates a local checkout in one call.
82+
83+
| Layer | Module | Purpose |
84+
|-------|--------|---------|
85+
| URL parsing | {mod}`libvcs.url` | Detect, validate, normalize VCS URLs |
86+
| Commands | {mod}`libvcs.cmd` | Execute individual VCS CLI operations |
87+
| Sync | {mod}`libvcs.sync` | Clone and update local repositories |
88+
89+
## Testing
90+
91+
libvcs ships a [pytest plugin](api/pytest-plugin.md) with
92+
session-scoped fixtures for Git, SVN, and Mercurial repositories:
93+
94+
```python
95+
def test_my_tool(create_git_remote_repo):
96+
repo_path = create_git_remote_repo()
97+
assert repo_path.exists()
1998
```
2099

21100
```{toctree}
22-
:caption: Project
23101
:hidden:
24102
25-
contributing/index
103+
quickstart
104+
topics/index
105+
api/index
26106
internals/index
107+
project/index
27108
history
28109
migration
29-
GitHub <https://github.com/vcs-python/libvcs>
30-
31110
```

‎docs/internals/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,56 @@ Be careful with these! Internal APIs are **not** covered by version policies. Th
88
If you need an internal API stabilized please [file an issue](https://github.com/vcs-python/libvcs/issues).
99
:::
1010

11+
::::{grid} 1 1 2 2
12+
:gutter: 2 2 3 3
13+
14+
:::{grid-item-card} Exceptions
15+
:link: exc
16+
:link-type: doc
17+
Error hierarchy for VCS operations.
18+
:::
19+
20+
:::{grid-item-card} Types
21+
:link: types
22+
:link-type: doc
23+
Shared type aliases and protocols.
24+
:::
25+
26+
:::{grid-item-card} Dataclasses
27+
:link: dataclasses
28+
:link-type: doc
29+
Internal dataclass utilities.
30+
:::
31+
32+
:::{grid-item-card} QueryList
33+
:link: query_list
34+
:link-type: doc
35+
Filterable list for object collections.
36+
:::
37+
38+
:::{grid-item-card} Run
39+
:link: run
40+
:link-type: doc
41+
Runtime helpers and environment utilities.
42+
:::
43+
44+
:::{grid-item-card} Subprocess
45+
:link: subprocess
46+
:link-type: doc
47+
Subprocess wrappers for VCS binaries.
48+
:::
49+
50+
:::{grid-item-card} Shortcuts
51+
:link: shortcuts
52+
:link-type: doc
53+
Convenience functions for common operations.
54+
:::
55+
56+
::::
57+
1158
```{toctree}
59+
:hidden:
60+
1261
exc
1362
types
1463
dataclasses

‎docs/project/code-style.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
(code-style)=
2+
3+
# Code Style
4+
5+
## Formatting and linting
6+
7+
libvcs uses [ruff](https://ruff.rs) for formatting **and** linting in a
8+
single tool. The full rule set is declared in `pyproject.toml` under
9+
`[tool.ruff]`.
10+
11+
```console
12+
$ uv run ruff format .
13+
```
14+
15+
```console
16+
$ uv run ruff check . --fix --show-fixes
17+
```
18+
19+
## Type checking
20+
21+
[mypy](http://mypy-lang.org/) runs in strict mode:
22+
23+
```console
24+
$ uv run mypy src tests
25+
```
26+
27+
## Docstrings
28+
29+
All public APIs use **NumPy-style** docstrings:
30+
31+
```python
32+
def fetch(url: str, *, branch: str | None = None) -> str:
33+
"""Fetch a remote branch.
34+
35+
Parameters
36+
----------
37+
url : str
38+
Repository URL.
39+
branch : str or None
40+
Branch name. ``None`` means the default branch.
41+
42+
Returns
43+
-------
44+
str
45+
The fetched commit hash.
46+
"""
47+
```
48+
49+
## Imports
50+
51+
- `from __future__ import annotations` at the top of every file.
52+
- Standard-library modules use **namespace imports**: `import pathlib`,
53+
not `from pathlib import Path`.
54+
- Typing: `import typing as t`, then `t.Optional`, `t.Any`, etc.

‎docs/project/contributing.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
(contributing)=
2+
3+
(developing)=
4+
5+
# Contributing
6+
7+
As an open source project, libvcs accepts contributions through GitHub.
8+
9+
Ready to dive in? See the [Development Workflow](workflow.md) for
10+
environment setup, running tests, linting, and building docs.

0 commit comments

Comments
 (0)