Skip to content

Commit eef5410

Browse files
tonytony
committed
docs(redesign): restructure documentation to Library Skeleton pattern
why: Landing page dumped the README. No unified API landing page for the 3 subsections (url, cmd, sync). No grid cards, no project/ section. what: - Compose standalone landing page with responsive grid cards - Create api/index.md as narrative hub for url/, cmd/, sync/ - Rename contributing/ to project/, add code-style, releasing - Move pytest-plugin.md under api/ - Add grid cards to all section index pages - Add sphinx-design dependency and extension - Add redirects for moved files
1 parent 54977ea commit eef5410

17 files changed

Lines changed: 474 additions & 43 deletions

File tree

‎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: 80 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,95 @@
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 1 2 2
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} Topics
19+
:link: topics/index
20+
:link-type: doc
21+
Traversal, filtering, and URL parsing patterns.
22+
:::
23+
24+
:::{grid-item-card} API Reference
25+
:link: api/index
26+
:link-type: doc
27+
URL parsing, commands, sync, and pytest plugin.
28+
:::
29+
30+
:::{grid-item-card} Project
31+
:link: project/index
32+
:link-type: doc
33+
Contributing, code style, release process.
34+
:::
35+
36+
::::
37+
38+
## Install
39+
40+
```console
41+
$ pip install libvcs
742
```
843

9-
```{toctree}
10-
:maxdepth: 2
11-
:hidden:
44+
```console
45+
$ uv add libvcs
46+
```
1247

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

2186
```{toctree}
22-
:caption: Project
2387
:hidden:
2488
25-
contributing/index
89+
quickstart
90+
topics/index
91+
api/index
2692
internals/index
93+
project/index
2794
history
2895
migration
29-
GitHub <https://github.com/vcs-python/libvcs>
30-
3196
```

‎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.

‎docs/project/index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
(project)=
2+
3+
# Project
4+
5+
Information for contributors and maintainers.
6+
7+
::::{grid} 1 1 2 2
8+
:gutter: 2 2 3 3
9+
10+
:::{grid-item-card} Contributing
11+
:link: contributing
12+
:link-type: doc
13+
Development setup, running tests, submitting PRs.
14+
:::
15+
16+
:::{grid-item-card} Development Workflow
17+
:link: workflow
18+
:link-type: doc
19+
Tests, documentation builds, formatting, and linting.
20+
:::
21+
22+
:::{grid-item-card} Code Style
23+
:link: code-style
24+
:link-type: doc
25+
Ruff, mypy, NumPy docstrings, import conventions.
26+
:::
27+
28+
:::{grid-item-card} Releasing
29+
:link: releasing
30+
:link-type: doc
31+
Release checklist and version policy.
32+
:::
33+
34+
::::
35+
36+
```{toctree}
37+
:hidden:
38+
39+
contributing
40+
workflow
41+
code-style
42+
releasing
43+
```

0 commit comments

Comments
 (0)