Merge pull request #536 from vcs-python/doc-redesign-spring-2026

docs(redesign): restructure documentation to Library Skeleton pattern

Author: tony

docs/api/index.md

@@ -3,23 +3,56 @@
 # API Reference
 
 :::{seealso}
-For granular control see the [libvcs documentation](https://libvcs.git-pull.com/en/latest/)—especially the sections on [commands](https://libvcs.git-pull.com/en/latest/usage/commands.html) and [projects](https://libvcs.git-pull.com/en/latest/usage/projects.html).
+For granular control see the [libvcs documentation](https://libvcs.git-pull.com/en/latest/)---especially the sections on [commands](https://libvcs.git-pull.com/en/latest/usage/commands.html) and [projects](https://libvcs.git-pull.com/en/latest/usage/projects.html).
 :::
 
-## Internals
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
 
-:::{warning}
-Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+:::{grid-item-card} vcspull.config
+:link: config
+:link-type: doc
+Configuration loading and repo extraction.
+:::
+
+:::{grid-item-card} vcspull.exc
+:link: exc
+:link-type: doc
+Exception hierarchy.
+:::
 
-If you need an internal API stabilized please [file an issue](https://github.com/vcs-python/vcspull/issues).
+:::{grid-item-card} vcspull.log
+:link: log
+:link-type: doc
+Logging helpers.
 :::
 
+:::{grid-item-card} vcspull.validator
+:link: validator
+:link-type: doc
+Config validation utilities.
+:::
+
+:::{grid-item-card} vcspull.util
+:link: util
+:link-type: doc
+General-purpose utilities.
+:::
+
+:::{grid-item-card} vcspull.types
+:link: types
+:link-type: doc
+Type definitions and aliases.
+:::
+
+::::
+
 ```{toctree}
+:hidden:
+
 config
-cli/index
 exc
 log
-internals/index
 validator
 util
 types

docs/cli/index.md

@@ -1,6 +1,73 @@
 (cli)=
 
-# Commands
+(commands)=
+
+# CLI Reference
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} vcspull sync
+:link: sync
+:link-type: doc
+Pull / clone repositories from config.
+:::
+
+:::{grid-item-card} vcspull add
+:link: add
+:link-type: doc
+Add a repository to your config file.
+:::
+
+:::{grid-item-card} vcspull list
+:link: list
+:link-type: doc
+List configured repositories.
+:::
+
+:::{grid-item-card} vcspull search
+:link: search
+:link-type: doc
+Search repos by name, path, or URL.
+:::
+
+:::{grid-item-card} vcspull status
+:link: status
+:link-type: doc
+Show working-tree status for each repo.
+:::
+
+:::{grid-item-card} vcspull discover
+:link: discover
+:link-type: doc
+Scan directories for existing repos.
+:::
+
+:::{grid-item-card} vcspull fmt
+:link: fmt
+:link-type: doc
+Normalize and format config files.
+:::
+
+:::{grid-item-card} vcspull import
+:link: import/index
+:link-type: doc
+Import repos from GitHub, GitLab, and more.
+:::
+
+:::{grid-item-card} vcspull worktree
+:link: worktree/index
+:link-type: doc
+Manage git worktrees declaratively.
+:::
+
+:::{grid-item-card} Completion
+:link: completion
+:link-type: doc
+Shell completions for bash, zsh, and fish.
+:::
+
+::::
 
 ```{toctree}
 :caption: General commands

docs/conf.py

@@ -40,9 +40,11 @@
  "sphinx_copybutton",
  "sphinxext.opengraph",
  "sphinxext.rediraffe",
+ "sphinx_design",
  "myst_parser",
  "linkify_issues",
 ]
+myst_heading_anchors = 4
 myst_enable_extensions = [
  "colon_fence",
  "substitution",

docs/configuration/index.md

@@ -2,6 +2,17 @@
 
 # Configuration
 
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Config Generation
+:link: generation
+:link-type: doc
+Import repos from forges and generate config automatically.
+:::
+
+::::
+
 ## URL Format
 
 Repo type and address is [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986) style URLs.
@@ -260,3 +271,9 @@ For git remotes using SSH authorization such as `git+git@github.com:tony/kaptan.
 ```console
 git+ssh://git@github.com/tony/kaptan.git
 ```
+
+```{toctree}
+:hidden:
+
+generation
+```

docs/index.md

@@ -4,37 +4,95 @@ hide-toc: true
 
 (index)=
 
-```{include} ../README.md
-:end-before: <img
-```
+# vcspull
 
-```{image} _static/vcspull-demo.gif
-:width: 100%
+CLI workspace manager for VCS repos. Sync, organize, and manage multiple
+git (and hg/svn) repositories from a single YAML config.
+
+::::{grid} 1 2 3 3
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Quickstart
+:link: quickstart
+:link-type: doc
+Install and sync your first repos.
+:::
+
+:::{grid-item-card} CLI Reference
+:link: cli/index
+:link-type: doc
+Every command, flag, and option.
+:::
+
+:::{grid-item-card} Configuration
+:link: configuration/index
+:link-type: doc
+Config format, locations, schema, and examples.
+:::
+
+::::
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} Internals
+:link: internals/index
+:link-type: doc
+Internal Python API for contributors.
+:::
+
+:::{grid-item-card} Contributing
+:link: project/index
+:link-type: doc
+Development setup, code style, and release process.
+:::
+
+::::
+
+## Install
+
+```console
+$ pip install vcspull
 ```
 
-# Donations
+```console
+$ uv tool install vcspull
+```
 
-```{include} ../README.md
-:start-after: "# Donations"
+```console
+$ pipx install vcspull
 ```
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+See [Quickstart](quickstart.md) for all installation methods and first steps.
 
-quickstart
-cli/index
-configuration/index
+## At a glance
+
+```yaml
+~/code/:
+ flask: "git+https://github.com/pallets/flask.git"
+ django: "git+https://github.com/django/django.git"
+~/study/:
+ linux: "git+https://github.com/torvalds/linux.git"
+```
 
+```console
+$ vcspull sync
+```
+
+```{image} _static/vcspull-demo.gif
+:width: 100%
+:loading: lazy
 ```
 
 ```{toctree}
-:caption: Project
 :hidden:
 
+quickstart
+cli/index
+configuration/index
 api/index
-developing
+internals/index
+project/index
 history
 migration
-GitHub <https://github.com/vcs-python/vcspull>
 ```