types+docs(feat[configuration]): Add py.typed marker and Pydantic model documentation

why: Improve type checking support and add comprehensive schema documentation for configuration
what:
- Add py.typed marker file for proper type checking
- Create types.py with ConfigDict TypedDict for fixtures
- Integrate autodoc_pydantic in Sphinx configuration
- Generate API reference for Pydantic models
- Add JSON Schema documentation from models
- Update documentation navigation for new schema pages
- Mark schema documentation tasks as complete in TODO

refs: Completes 'Generate schema documentation from models' task

Author: tony

docs/api/config_models.md

@@ -0,0 +1,39 @@
+# Configuration Models - `vcspull.config.models`
+
+This page documents the Pydantic models used to configure VCSPull.
+
+## Repository Model
+
+The Repository model represents a single repository configuration.
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.Repository
+   :inherited-members: BaseModel
+   :model-show-json: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+```
+
+## Settings Model
+
+The Settings model controls global behavior of VCSPull.
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.Settings
+   :inherited-members: BaseModel
+   :model-show-json: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+```
+
+## VCSPullConfig Model
+
+The VCSPullConfig model is the root configuration model for VCSPull.
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.VCSPullConfig
+   :inherited-members: BaseModel
+   :model-show-json: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+``` 

docs/api/index.md

@@ -6,6 +6,13 @@
 For granular control see {ref}`libvcs <libvcs:index>`'s {ref}`Commands <libvcs:cmd>` and {ref}`Projects <libvcs:projects>`.
 :::
 
+## Configuration
+
+```{toctree}
+config
+config_models
+```
+
 ## Internals
 
 :::{warning}
@@ -15,7 +22,6 @@ If you need an internal API stabilized please [file an issue](https://github.com
 :::
 
 ```{toctree}
-config
 cli/index
 exc
 log

docs/conf.py

@@ -41,6 +41,7 @@
     "sphinxext.rediraffe",
     "myst_parser",
     "linkify_issues",
+    "sphinxcontrib.autodoc_pydantic",
 ]
 myst_enable_extensions = [
     "colon_fence",
@@ -122,6 +123,19 @@
 autodoc_typehints = "description"  # show type hints in doc body instead of signature
 simplify_optional_unions = True
 
+# autodoc_pydantic configuration
+autodoc_pydantic_model_show_json = True
+autodoc_pydantic_model_show_config = True
+autodoc_pydantic_model_show_validator_members = True
+autodoc_pydantic_model_show_field_summary = True
+autodoc_pydantic_model_member_order = "bysource"
+autodoc_pydantic_model_hide_paramlist = False
+autodoc_pydantic_model_undoc_members = True
+autodoc_pydantic_field_list_validators = True
+autodoc_pydantic_field_show_constraints = True
+autodoc_pydantic_settings_show_json = True
+autodoc_pydantic_settings_show_config = True
+
 # sphinx.ext.napoleon
 napoleon_google_docstring = True
 napoleon_include_init_with_doc = True

docs/configuration/index.md

@@ -93,6 +93,7 @@ YAML:
 :hidden:
 
 generation
+schema
 ```
 
 ## Caveats

docs/configuration/schema.md

@@ -0,0 +1,36 @@
+# Configuration Schema
+
+This page provides the detailed JSON Schema for the VCSPull configuration.
+
+## JSON Schema
+
+The following schema is automatically generated from the VCSPull configuration models.
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.VCSPullConfig
+   :model-show-json-schema: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+```
+
+## Repository Schema
+
+Individual repository configuration schema:
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.Repository
+   :model-show-json-schema: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+```
+
+## Settings Schema
+
+Global settings configuration schema:
+
+```{eval-rst}
+.. autopydantic_model:: vcspull.config.models.Settings
+   :model-show-json-schema: True
+   :model-show-field-summary: True
+   :field-signature-prefix: param
+```