url(docs): Add Attributes to Rule and URL parsers

why: Autodoc renders every dataclass field, so the parsed URL
fields shipped bare in the API reference. Rule's per-field
docstrings also sat one field below what they described, so
readers matched "Weight: Higher is more likely to win" to
is_explicit.

what:
- Move Rule's field docstrings into an Attributes section, paired
  with the field each describes, and cover defaults and weight
- Document the parsed fields of GitBaseURL, HgBaseURL, SvnBaseURL,
  including which sentinel each carries when a rule captures
  nothing
- Document region and rev on GitAWSCodeCommitURL, and rev on the
  pip URL parsers

Author: tony

src/libvcs/url/base.py

@@ -28,18 +28,32 @@ def is_valid(cls, url: str, is_explicit: bool | None = None) -> bool:
 
 @dataclasses.dataclass(repr=False)
 class Rule(SkipDefaultFieldsReprMixin):
-    """A Rule represents an eligible pattern mapping to URL."""
+    """A Rule represents an eligible pattern mapping to URL.
+
+    Attributes
+    ----------
+    label : str
+        Computer readable name / ID. Keys the rule inside a
+        :class:`RuleMap` and is recorded on a matched URL's ``rule``.
+    description : str
+        Human readable description of the URL shape the rule covers.
+    pattern : Pattern[str]
+        Regex pattern. Its named groups are assigned onto the URL object's
+        fields of the same name.
+    defaults : dict[str, str]
+        Values to apply to fields the pattern left unset, e.g. the
+        ``hostname`` and ``scheme`` a bare prefix such as ``github:`` implies.
+    is_explicit : bool
+        Is the match unambiguous with other VCS systems? e.g. git+ prefix
+    weight : int
+        Weight: Higher is more likely to win
+    """
 
     label: str
-    """Computer readable name / ID"""
     description: str
-    """Human readable description"""
     pattern: Pattern[str]
-    """Regex pattern"""
     defaults: dict[str, str] = dataclasses.field(default_factory=dict)
-    """Is the match unambiguous with other VCS systems? e.g. git+ prefix"""
     is_explicit: bool = False
-    """Weight: Higher is more likely to win"""
     weight: int = 0
 
 

src/libvcs/url/git.py

@@ -294,6 +294,32 @@ class GitBaseURL(
 ):
     """Git repository location. Parses URLs on initialization.
 
+    Attributes
+    ----------
+    url : str
+        Location as given, kept verbatim. Every other field is filled from it
+        by the first :class:`~libvcs.url.base.Rule` that matches.
+    scheme : str | None
+        Transport scheme, e.g. ``https`` or ``ssh``. ``None`` for scp-style
+        locations such as ``git@github.com:vcs-python/libvcs.git``, which
+        carry no scheme.
+    user : str | None
+        User in front of the hostname, e.g. ``git``. ``None`` when the URL
+        omits one; :meth:`to_url` falls back to ``git`` for scp-style output.
+    hostname : str | None
+        Server hosting the repository, e.g. ``github.com``.
+    port : int | None
+        Port the URL specifies, or ``None`` to use the transport's default.
+    path : str | None
+        Server-side path to the repository with the suffix split off, e.g.
+        ``vcs-python/libvcs``.
+    suffix : str | None
+        Trailing ``.git`` split off the path, or ``None`` when the URL has
+        none. :meth:`to_url` re-appends it.
+    rule : str | None
+        :attr:`~libvcs.url.base.Rule.label` of the rule that matched, or
+        ``None`` when no rule did and the remaining fields stayed unset.
+
     Examples
     --------
     >>> GitBaseURL(url='https://github.com/vcs-python/libvcs.git')
@@ -454,7 +480,21 @@ class GitAWSCodeCommitURL(
     URLProtocol,
     SkipDefaultFieldsReprMixin,
 ):
-    """Supports AWS CodeCommit git URLs."""
+    """Supports AWS CodeCommit git URLs.
+
+    Parses the fields of :class:`GitBaseURL` plus the two below.
+
+    Attributes
+    ----------
+    region : str | None
+        AWS region from a ``codecommit::<region>://`` URL, e.g.
+        ``us-east-1``. ``None`` for region-less GRC URLs and for the HTTPS
+        and SSH forms, which carry the region inside the hostname.
+    rev : str | None
+        Commit-ish (tag, branch, ref) trailing the URL as ``@rev``, or
+        ``None`` when the URL names no revision. :meth:`to_url` re-appends
+        it.
+    """
 
     # AWS CodeCommit Region
     region: str | None = None
@@ -589,7 +629,17 @@ class GitPipURL(
     URLProtocol,
     SkipDefaultFieldsReprMixin,
 ):
-    """Supports pip git URLs."""
+    """Supports pip git URLs.
+
+    Parses the fields of :class:`GitBaseURL` plus the one below.
+
+    Attributes
+    ----------
+    rev : str | None
+        Commit-ish (tag, branch, ref) from a pip-style ``@rev``, e.g.
+        ``v0.10.0``. ``None`` when the URL names no revision.
+        :meth:`to_url` re-appends it.
+    """
 
     # commit-ish (rev): tag, branch, ref
     rev: str | None = None

src/libvcs/url/hg.py

@@ -154,6 +154,38 @@ class HgBaseURL(
 ):
     """Mercurial repository location. Parses URLs on initialization.
 
+    Attributes
+    ----------
+    url : str
+        Location as given, kept verbatim. Every other field is filled from it
+        by the first :class:`~libvcs.url.base.Rule` that matches.
+    scheme : str | None
+        Transport scheme, e.g. ``https``, ``ssh``, or ``hg+file``. ``None``
+        when the matched rule captured none.
+    user : str | None
+        User in front of the hostname, e.g. ``hg``. ``None`` when the URL
+        omits one; :meth:`to_url` falls back to ``hg`` for scp-style output.
+    hostname : str
+        Server hosting the repository, e.g. ``hg.mozilla.org``. Empty when
+        the matched rule captures no host, as with ``hg+file://`` URLs.
+    port : int | None
+        Port the URL specifies, or ``None`` to use the transport's default.
+    separator : str
+        Character sitting between the host (and port) and the path, ``/``
+        unless the URL used ``:`` or ``,``. :meth:`to_url` re-emits it.
+    path : str
+        Server-side path to the repository, e.g. ``mozilla-central/``. Empty
+        when the URL carries no path.
+    suffix : str | None
+        Trailing ``.git``-style decoration split off the path, or ``None``
+        when the URL has none.
+    ref : str | None
+        Commit-ish (tag, branch, ref, revision) for callers to set; the
+        bundled rules capture no ref, so parsing leaves it ``None``.
+    rule : str | None
+        :attr:`~libvcs.url.base.Rule.label` of the rule that matched, or
+        ``None`` when no rule did and the remaining fields stayed unset.
+
     Examples
     --------
     >>> HgBaseURL(url='https://hg.mozilla.org/mozilla-central/')
@@ -341,7 +373,16 @@ class HgPipURL(
     URLProtocol,
     SkipDefaultFieldsReprMixin,
 ):
-    """Supports pip hg URLs."""
+    """Supports pip hg URLs.
+
+    Parses the fields of :class:`HgBaseURL` plus the one below.
+
+    Attributes
+    ----------
+    rev : str | None
+        Commit-ish (tag, branch, ref) from a pip-style ``@rev``, e.g.
+        ``v1.0``. ``None`` when the URL names no revision.
+    """
 
     # commit-ish (rev): tag, branch, ref
     rev: str | None = None

src/libvcs/url/svn.py

@@ -150,6 +150,36 @@ class SvnBaseURL(
 ):
     """SVN repository location. Parses URLs on initialization.
 
+    Attributes
+    ----------
+    url : str
+        Location as given, kept verbatim. Every other field is filled from it
+        by the first :class:`~libvcs.url.base.Rule` that matches.
+    scheme : str | None
+        Transport scheme, e.g. ``https``, ``svn+ssh``, or ``svn+file``.
+        ``None`` for scp-style locations, which carry no scheme.
+    user : str | None
+        User in front of the hostname, e.g. ``svn``. ``None`` when the URL
+        omits one.
+    hostname : str
+        Server hosting the repository, e.g. ``svn.debian.org``. Empty when
+        the matched rule captures no host, as with ``svn+file://`` URLs.
+    port : int | None
+        Port the URL specifies, or ``None`` to use the transport's default.
+    separator : str
+        Character sitting between the host (and port) and the path, ``/``
+        unless the URL used ``:`` or ``,``. :meth:`to_url` re-emits it.
+    path : str
+        Server-side path to the repository, e.g.
+        ``svn/aliothproj/path/in/project``. Empty when the URL carries no
+        path.
+    ref : str | None
+        Commit-ish (tag, branch, revision) for callers to set; the bundled
+        rules capture no ref, so parsing leaves it ``None``.
+    rule : str | None
+        :attr:`~libvcs.url.base.Rule.label` of the rule that matched, or
+        ``None`` when no rule did and the remaining fields stayed unset.
+
     Examples
     --------
     >>> SvnBaseURL(
@@ -279,7 +309,16 @@ class SvnPipURL(
     URLProtocol,
     SkipDefaultFieldsReprMixin,
 ):
-    """Supports pip svn URLs."""
+    """Supports pip svn URLs.
+
+    Parses the fields of :class:`SvnBaseURL` plus the one below.
+
+    Attributes
+    ----------
+    rev : str | None
+        Commit-ish (tag, branch, revision) from a pip-style ``@rev``, e.g.
+        ``2019``. ``None`` when the URL names no revision.
+    """
 
     # commit-ish (rev): tag, branch, ref
     rev: str | None = None