Massively improved the docstrings for each module and some classes.

Author: Ben Davis

src/fastsandpm/__init__.py

@@ -32,19 +32,26 @@
     >>> manifest = fastsandpm.get_manifest("./my-project")
     >>> print(manifest.package.name)
     'my-package'
+    >>> resolved = fastsandpm.dependencies.resolve(manifest)
+    >>> print(type(resolved))
+    <class 'dict'>
+    >>> build_library(resolved, pathlib.Path("my-library"))
 
-Classes:
-    Manifest: The main manifest model representing a proj.toml file.
-    Package: Package metadata (name, version, description, authors).
-    ManifestNotFoundError: Raised when a manifest file cannot be found.
-    ManifestParseError: Raised when a manifest file cannot be parsed.
+Included Classes:
+    - :py:class:`~manifest.Manifest`: The main manifest model representing a `proj.toml` file.
+    - :py:class:`~manifest.Package`: Package metadata (name, version, description, authors).
+    - :py:class:`~manifest.ManifestNotFoundError`: Raised when a manifest file cannot be found.
+    - :py:class:`~manifest.ManifestParseError`: Raised when a manifest file cannot be parsed.
 
 Functions:
-    get_manifest: Load and parse a manifest from a repository path.
+    - :py:func:`~manifest.get_manifest`: Load and parse a manifest from a repository path.
+    - :py:func:`~dependencies.resolve`: Resolve all dependencies for a manifest.
+    - :py:func:`~install.build_library`: Build a library from a resovled dependency definition.
+    - :py:func:`~install.library_from_manifest`: Build a library of dependencies from a manifest.
 
 Attributes:
-    __version__: The current version of the FastSandPM package.
-    __author__: The primary author of the package.
+    __version__ (str): The current version of the FastSandPM package.
+    __author__ (str): The primary author of the package.
 
 See Also:
     - fastsandpm.dependencies: Dependency resolution subpackage

src/fastsandpm/_git_utils.py

@@ -24,36 +24,35 @@
 git-based sources.
 
 Repository Operations:
-    clone: Clone a repository from a remote URL.
-    checkout: Checkout a specific commit, branch, or tag.
-    fetch: Fetch updates from the remote repository.
+    - clone: Clone a repository from a remote URL.
+    - checkout: Checkout a specific commit, branch, or tag.
+    - fetch: Fetch updates from the remote repository.
 
 Repository State:
-    is_dirty: Check if a repository has uncommitted changes.
-    is_git_repo: Check if a path is a git repository.
-    get_head_commit: Get the HEAD commit hash.
-    get_current_branch: Get the current branch name.
-    get_tags_at_head: Get all tags pointing to HEAD.
-    get_remote_url: Get the URL of a remote.
+    - is_dirty: Check if a repository has uncommitted changes.
+    - is_git_repo: Check if a path is a git repository.
+    - get_head_commit: Get the HEAD commit hash.
+    - get_current_branch: Get the current branch name.
+    - get_tags_at_head: Get all tags pointing to HEAD.
+    - get_remote_url: Get the URL of a remote.
 
 Remote Operations:
-    remote_exists: Check if a remote repository is accessible.
-    get_available_tags: Get all tags from a remote repository.
-    get_remote_refs: Get all refs grouped by commit hash (cached).
-    get_commit_for_ref: Get commit hash for a specific ref.
-    get_remote_file: Fetch a single file from a remote repository.
+    - remote_exists: Check if a remote repository is accessible.
+    - get_available_tags: Get all tags from a remote repository.
+    - get_remote_refs: Get all refs grouped by commit hash (cached).
+    - get_commit_for_ref: Get commit hash for a specific ref.
+    - get_remote_file: Fetch a single file from a remote repository.
 
 URL Parsing:
-    parse_github_url: Parse GitHub URLs to extract owner/repo.
-    parse_gitlab_url: Parse GitLab URLs to extract host/project path.
+    - parse_github_url: Parse GitHub URLs to extract owner/repo.
+    - parse_gitlab_url: Parse GitLab URLs to extract host/project path.
 
 Hosting Provider APIs:
-    fetch_file_from_github: Fetch a file via GitHub raw content URL.
-    fetch_file_from_gitlab: Fetch a file via GitLab repository API.
-    fetch_file_from_hosting_api: Try fetching via supported hosting APIs.
+    - fetch_file_from_github: Fetch a file via GitHub raw content URL.
+    - fetch_file_from_gitlab: Fetch a file via GitLab repository API.
+    - fetch_file_from_hosting_api: Try fetching via supported hosting APIs.
 
-Note:
-    This module requires git to be installed and available in the system PATH.
+.. note:: This module requires git to be installed and available in the system PATH.
 """
 
 from __future__ import annotations

src/fastsandpm/dependencies/__init__.py

@@ -22,28 +22,25 @@
 including requirement definitions, candidate generation, and resolution
 algorithms.
 
-Modules:
-    requirements: Defines requirement types for different dependency sources.
-    candidates: Implements candidate generation from requirements.
-    provider: Provides the dependency resolution provider for resolvelib.
+Included Classes:
+    - :py:class:`~requirements.ConcreteRequirement`: Union type of all concrete requirement types.
+    - :py:class:`~requirements.GitRequirement`: Base class for git-based requirements.
+    - :py:class:`~requirements.BranchGitRequirement`: Git requirement pinned to a specific branch.
+    - :py:class:`~requirements.CommitGitRequirement`: Git requirement pinned to a specific commit.
+    - :py:class:`~requirements.TaggedGitRequirement`: Git requirement pinned to a specific tag.
+    - :py:class:`~requirements.VersionedGitRequirement`: Git requirement with version constraints.
+    - :py:class:`~requirements.PackageIndexRequirement`: Requirement from a package index.
+    - :py:class:`~requirements.PathRequirement`: Requirement from a local filesystem path.
+    - :py:class:`~candidates.Candidate`: Abstract base class for dependency candidates.
+    - :py:class:`~candidates.PackageIndexCandidate`: Candidate from a package index registry.
+    - :py:class:`~candidates.PathCandidate`: Candidate from a local filesystem path.
+    - :py:class:`~candidates.GitCandidate`: Candidate from a git repository.
 
-Classes:
-    ConcreteRequirement: Union type of all concrete requirement types.
-    GitRequirement: Base class for git-based requirements.
-    BranchGitRequirement: Git requirement pinned to a specific branch.
-    CommitGitRequirement: Git requirement pinned to a specific commit.
-    TaggedGitRequirement: Git requirement pinned to a specific tag.
-    VersionedGitRequirement: Git requirement with version constraints.
-    PackageIndexRequirement: Requirement from a package index.
-    PathRequirement: Requirement from a local filesystem path.
-    Candidate: Abstract base class for dependency candidates.
-    PackageIndexCandidate: Candidate from a package index registry.
-    PathCandidate: Candidate from a local filesystem path.
-    GitCandidate: Candidate from a git repository.
+Included Functions:
+    - :py:func:`~candidates.candidate_factory`: Singledispatch function to create candidates
+      from requirements.
 
-Functions:
-    candidate_factory: Singledispatch function to create candidates from requirements.
-    resolve: Resolve all dependencies for a manifest.
+    - :py:func:`~provider.resolve`: Resolve all dependencies for a manifest.
 """
 
 from __future__ import annotations

src/fastsandpm/dependencies/candidates.py

@@ -23,13 +23,13 @@
 concrete versions of dependencies that can satisfy requirements.
 
 Classes:
-    Candidate: Abstract base class for all candidate types.
-    PackageIndexCandidate: Candidate from a package index registry.
-    PathCandidate: Candidate from a local filesystem path.
-    GitCandidate: Candidate from a git repository.
+    - :py:class:`Candidate`: Abstract base class for all candidate types.
+    - :py:class:`PackageIndexCandidate`: Candidate from a package index registry.
+    - :py:class:`PathCandidate`: Candidate from a local filesystem path.
+    - :py:class:`GitCandidate`: Candidate from a git repository.
 
 Functions:
-    candidate_factory: Singledispatch function to create candidates from requirements.
+    - :py:func:`candidate_factory`: Singledispatch function to create candidates from requirements.
 """
 
 from __future__ import annotations
@@ -87,6 +87,7 @@ def satisfies(self, requirement: ConcreteRequirement) -> bool:
         """Check if this candidate satisfies the given requirement.
 
         A candidate satisfies a requirement when:
+
         - The requirement name and candidate name match
         - If the requirement specifies a version, the candidate's version matches
 
@@ -114,8 +115,9 @@ class PackageIndexCandidate(Candidate):
     Artifactory. This implementation is currently a placeholder as package
     index registries are not yet fully implemented.
 
-    Note:
-        Package index registry support is under development.
+    .. warning::
+
+        Package index registry support is under development and is not currently implemented.
     """
 
     def get_manifest(self) -> Manifest | None:
@@ -169,9 +171,9 @@ def satisfies(self, requirement: ConcreteRequirement) -> bool:
         A path candidate satisfies a requirement when the requirement name
         and candidate name match, and type-specific conditions are met:
 
-        * For PackageIndexRequirement: the candidate's version matches the specifier
-        * For PathRequirement: the candidate path ends with the requirement path
-        * For Git requirements: the path is a git repo and HEAD complies with
+        - For PackageIndexRequirement: the candidate's version matches the specifier
+        - For PathRequirement: the candidate path ends with the requirement path
+        - For Git requirements: the path is a git repo and HEAD complies with
           the requirement's constraints (commit, branch, tag, or version)
 
         Args:
@@ -191,7 +193,7 @@ def satisfies(self, requirement: ConcreteRequirement) -> bool:
             req_parts = requirement.path.parts
             cand_parts = self.path.parts
             if len(req_parts) <= len(cand_parts):
-                return cand_parts[-len(req_parts) :] == req_parts
+                return cand_parts[-len(req_parts):] == req_parts
             return False
 
         # Handle Git requirements: check if candidate points to a git repo
@@ -327,6 +329,7 @@ def satisfies(self, requirement: ConcreteRequirement) -> bool:
         """Check if this git candidate satisfies the given requirement.
 
         A git candidate satisfies a requirement when:
+
         - The requirement name and candidate name match
         - If the requirement specifies a version, the candidate's version matches
         - For PackageIndexRequirement: only if no specific index is required
@@ -400,9 +403,15 @@ def candidate_factory(
     Yields:
         Candidate objects that could satisfy the requirement.
 
-    Note:
+    .. note::
+
         The base implementation yields no candidates. Specialized implementations
-        are registered for each concrete requirement type.
+        are registered for each concrete requirement type through the singledispatch.
+
+    .. note::
+
+        Package index registries are not yet implemented, so this currently
+        yields no candidates.
     """
     yield from []
 
@@ -420,8 +429,7 @@ def _package_index_candidate_factory(
     Yields:
         PackageIndexCandidate objects matching the requirement.
 
-    Note:
-        Package index registries are not yet implemented, so this currently
+    .. note:: Package index registries are not yet implemented, so this currently
         yields no candidates.
     """
     yield from []

src/fastsandpm/dependencies/provider.py

@@ -23,14 +23,14 @@
 and dependency extraction during the resolution process.
 
 Classes:
-    FastSandProvider: The main dependency resolution provider.
+    - :py:class:`~FastSandProvider`: The main dependency resolution provider.
 
 Functions:
-    resolve: Convenience function to resolve dependencies for a manifest.
+    - :py:func:`~resolve`: Convenience function to resolve dependencies for a manifest.
 
 Type Aliases:
-    FastSandReqInfo: Type alias for requirement information tuples.
-    FastSandReporter: Type alias for the resolution reporter.
+    - :py:type:`~FastSandReqInfo`: FastSandReqInfo: Type alias for requirement information tuples.
+    - :py:type:`~FastSandReporter`: Type alias for the resolution reporter.
 """
 
 from __future__ import annotations
@@ -59,6 +59,9 @@
 
 
 FastSandReqInfo = RequirementInformation[ConcreteRequirement, Candidate]
+""".. py:type:: FastSandReqInfo:
+    Type alias for requirement information tuples.
+"""
 
 
 class FastSandProvider(resolvelib.AbstractProvider[ConcreteRequirement, Candidate, str]):
@@ -279,6 +282,7 @@ def narrow_requirement_selection(
 
 
 FastSandReporter = resolvelib.BaseReporter[ConcreteRequirement, Candidate, str]
+"""Type alias for the resolution reporter."""
 
 
 def resolve(manifest: Manifest) -> dict[str, Candidate]:

src/fastsandpm/manifest.py

@@ -23,18 +23,18 @@
 of package metadata, dependencies, and registry configurations.
 
 Classes:
-    ManifestNotFoundError: Exception raised when manifest file is not found.
-    ManifestParseError: Exception raised when manifest parsing fails.
-    Package: Package metadata (name, version, description, authors).
-    Dependencies: Collection of package dependencies.
-    Manifest: The complete manifest model.
+    - :py:exc:`~ManifestNotFoundError`: Exception raised when manifest file is not found.
+    - :py:exc:`~ManifestParseError`: Exception raised when manifest parsing fails.
+    - :py:class:`~Package`: Package metadata (name, version, description, authors).
+    - :py:class:`~Dependencies`: Collection of package dependencies.
+    - :py:class:`~Manifest`: The complete manifest model.
 
 Functions:
-    get_manifest: Load and parse a manifest from a repository path.
-    get_manifest_from_bytes: Parse a manifest from raw bytes content.
+    - :py:func:`~get_manifest`: Load and parse a manifest from a repository path.
+    - :py:func:`~get_manifest_from_bytes`: Parse a manifest from raw bytes content.
 
 Constants:
-    MANIFEST_FILENAME: The default manifest filename ("proj.toml").
+    - :py:const:`~MANIFEST_FILENAME`: The default manifest filename ("proj.toml").
 
 Example:
     >>> from fastsandpm.manifest import get_manifest
@@ -157,7 +157,15 @@ class Dependencies(RootModel[list[ConcreteRequirement]]):
     The model validator automatically converts dictionary-style TOML
     dependencies into the correct dependency type based on the keys present.
 
-    Example:
+    Example TOML:
+        .. code-block:: toml
+
+            [dependencies]
+
+            my-lib = "1.0.0"
+            other_lib = {git = "https://github.com/username/repo.git", tag = "v1.0.0"}
+
+    Example Usage:
         >>> deps = manifest.dependencies
         >>> for dep in deps:
         ...     print(dep.name)

src/fastsandpm/registries.py

@@ -22,14 +22,14 @@
 various sources including git hosts, package indices, and local paths.
 
 Classes:
-    DependencyNotFoundError: Exception raised when a dependency cannot be found.
-    GitRegistry: Registry for resolving dependencies from git hosts.
-    PackageIndexRegistery: Registry for resolving dependencies from package indices.
-    PathRegistry: Registry for resolving dependencies from local filesystem paths.
-    Registries: Collection of registries used during dependency resolution.
+    - :py:exc:`~DependencyNotFoundError`: Exception raised when a dependency cannot be found.
+    - :py:class:`~GitRegistry`: Registry for resolving dependencies from git hosts.
+    - :py:class:`~PackageIndexRegistery`: Registry for resolving dependencies from package indices.
+    - :py:class:`~PathRegistry`: Registry for resolving dependencies from local filesystem paths.
+    - :py:class:`~Registries`: Collection of registries used during dependency resolution.
 
 Type Aliases:
-    ConcreteRegistry: Union type of all concrete registry types.
+    - :py:type:`~ConcreteRegistry`: Union type of all concrete registry types.
 """
 
 from __future__ import annotations
@@ -139,12 +139,12 @@ def parse_dependencies(cls, data: Any) -> Any:
         Returns:
             A list of registry dictionaries ready for model instantiation.
 
-        Examples:
-            Input formats supported:
-            - {"name": "foo", "remote": "url"} -> [{"name": "foo", ...}]
-            - {"foo": "url"} -> [{"name": "foo", "remote": "url"}]
-            - {"foo": {"remote": "url"}} -> [{"name": "foo", "remote": "url"}]
-            - {"foo": {"path": "./path"}} -> [{"name": "foo", "path": "./path"}]
+        Example Input formats supported:
+
+            - ``{"name": "foo", "remote": "url"} -> [{"name": "foo", ...}]``
+            - ``{"foo": "url"} -> [{"name": "foo", "remote": "url"}]``
+            - ``{"foo": {"remote": "url"}} -> [{"name": "foo", "remote": "url"}]``
+            - ``{"foo": {"path": "./path"}} -> [{"name": "foo", "path": "./path"}]``
         """
         if isinstance(data, dict):
             # Handle single dependency passed as dict with 'name' key

src/fastsandpm/versioning/__init__.py

@@ -33,19 +33,21 @@
     - Comparison: ``">=1.0.0"``, ``"<2.0.0"``
     - Range: ``">=1.0.0,<2.0.0"``
 
-Classes:
-    PreReleaseStage: Enum for pre-release stages (ALPHA, BETA, RELEASE_CANDIDATE).
-    LibraryVersion: Represents and compares semantic versions.
-    VersionSpecifier: Abstract base class for version specifications.
-    DirectVersionSpecifier: Matches a single version exactly.
-    CaretVersionSpecifier: Matches semver-compatible versions (^x.y.z).
-    ComparisonVersionSpecifier: Matches using comparison operators.
-    RangeVersionSpecifier: Matches versions within a range.
+Included Classes:
+    - :py:enim`~library_version.PreReleaseStage`: Enum for pre-release stages.
+    - :py:class`~library_version.LibraryVersion`: Represents and compares semantic versions.
+    - :py:class`~specifier.VersionSpecifier`: Abstract base class for version specifications.
+    - :py:class`~specifier.DirectVersionSpecifier`: Matches a single version exactly.
+    - :py:class`~specifier.CaretVersionSpecifier`: Matches semver-compatible versions (^x.y.z).
+    - :py:class`~specifier.ComparisonVersionSpecifier`: Matches using comparison operators.
+    - :py:class`~specifier.RangeVersionSpecifier`: Matches versions within a range.
 
-Functions:
-    meets_constraints: Check if a version meets specified constraints.
-    find_compatible_version: Find the best matching version from available options.
-    version_specifier_from_str: Parse a version specifier string.
+Included Functions:
+
+    - :py:func:`~specifier.meets_constraints`: Check if a version meets specified constraints.
+    - :py:func:`~specifier.find_compatible_version`: Find the best matching version from
+      a list of options.
+    - :py:func:`~specifier.version_specifier_from_str`: Parse a version specifier string.
 
 Example:
     >>> from fastsandpm.versioning import LibraryVersion, version_specifier_from_str