Doc fixes (#490)

Author: tony

CHANGES

@@ -31,6 +31,15 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
+### Documentation
+
+#### Fix Sphinx autodoc indentation errors (#490)
+
+- Configure `sphinx-autodoc-typehints` to prevent RST parsing conflicts with
+  Napoleon-processed docstrings by disabling type injection into docstring
+  bodies (`always_document_param_types`, `typehints_document_rtype`).
+- Suppress cosmetic forward reference warnings from TYPE_CHECKING imports.
+
 _Upcoming changes will be written here._
 
 ## vcspull v1.48.0 (2025-11-30)

docs/api/index.md

@@ -3,7 +3,7 @@
 # API Reference
 
 :::{seealso}
-For granular control see {ref}`libvcs <libvcs:index>`'s {ref}`Commands <libvcs:cmd>` and {ref}`Projects <libvcs:projects>`.
+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

docs/conf.py

@@ -118,9 +118,18 @@
     "member-order": "bysource",
 }
 
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+# Don't show class signature with the class' name.
+autodoc_class_signature = "separated"
+
 # sphinx-autodoc-typehints
-autodoc_typehints = "description"  # show type hints in doc body instead of signature
-simplify_optional_unions = True
+# Suppress warnings for forward references that can't be resolved
+# (types in TYPE_CHECKING blocks used for circular import avoidance)
+suppress_warnings = [
+    "sphinx_autodoc_typehints.forward_reference",
+]
 
 # sphinx.ext.napoleon
 napoleon_google_docstring = True

src/vcspull/_internal/config_reader.py

@@ -7,12 +7,8 @@
 
 import yaml
 
-if t.TYPE_CHECKING:
-    from typing import Literal, TypeAlias
-
-    FormatLiteral = Literal["json", "yaml"]
-
-    RawConfigData: TypeAlias = dict[t.Any, t.Any]
+FormatLiteral = t.Literal["json", "yaml"]
+RawConfigData: t.TypeAlias = dict[t.Any, t.Any]
 
 
 class ConfigReader:

src/vcspull/cli/add.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import copy
 import logging
 import pathlib
@@ -23,9 +24,6 @@
     workspace_root_label,
 )
 
-if t.TYPE_CHECKING:
-    import argparse
-
 log = logging.getLogger(__name__)
 
 

src/vcspull/cli/discover.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import logging
 import os
 import pathlib
@@ -23,9 +24,6 @@
     workspace_root_label,
 )
 
-if t.TYPE_CHECKING:
-    import argparse
-
 log = logging.getLogger(__name__)
 
 ConfigScope = t.Literal["system", "user", "project", "external"]

src/vcspull/cli/fmt.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import copy
 import logging
 import pathlib
@@ -20,9 +21,6 @@
     save_config_yaml,
 )
 
-if t.TYPE_CHECKING:
-    import argparse
-
 log = logging.getLogger(__name__)
 
 

src/vcspull/cli/list.py

@@ -2,22 +2,18 @@
 
 from __future__ import annotations
 
+import argparse
 import logging
-import typing as t
+import pathlib
 
 from vcspull._internal.private_path import PrivatePath
 from vcspull.config import filter_repos, find_config_files, load_configs
+from vcspull.types import ConfigDict
 
 from ._colors import Colors, get_color_mode
 from ._output import OutputFormatter, get_output_mode
 from ._workspaces import filter_by_workspace
 
-if t.TYPE_CHECKING:
-    import argparse
-    import pathlib
-
-    from vcspull.types import ConfigDict
-
 log = logging.getLogger(__name__)
 
 

src/vcspull/cli/status.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import asyncio
 import logging
 import os
@@ -15,16 +16,12 @@
 
 from vcspull._internal.private_path import PrivatePath
 from vcspull.config import filter_repos, find_config_files, load_configs
+from vcspull.types import ConfigDict
 
 from ._colors import Colors, get_color_mode
 from ._output import OutputFormatter, get_output_mode
 from ._workspaces import filter_by_workspace
 
-if t.TYPE_CHECKING:
-    import argparse
-
-    from vcspull.types import ConfigDict
-
 log = logging.getLogger(__name__)
 
 DEFAULT_STATUS_CONCURRENCY = max(1, min(32, (os.cpu_count() or 4) * 2))

src/vcspull/cli/sync.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import asyncio
 import contextlib
 import json
@@ -20,11 +21,14 @@
 from time import perf_counter
 
 from libvcs._internal.shortcuts import create_project
+from libvcs._internal.types import VCSLiteral
+from libvcs.sync.git import GitSync
 from libvcs.url import registry as url_tools
 
 from vcspull import exc
 from vcspull._internal.private_path import PrivatePath
 from vcspull.config import filter_repos, find_config_files, load_configs
+from vcspull.types import ConfigDict
 
 from ._colors import Colors, get_color_mode
 from ._output import (
@@ -40,14 +44,6 @@
 from ._workspaces import filter_by_workspace
 from .status import check_repo_status
 
-if t.TYPE_CHECKING:
-    import argparse
-
-    from libvcs._internal.types import VCSLiteral
-    from libvcs.sync.git import GitSync
-
-    from vcspull.types import ConfigDict
-
 log = logging.getLogger(__name__)
 
 ProgressCallback = Callable[[str, datetime], None]