- Restore docs autorefs as explained in mkdocstrings/mkdocstrings#226 (comment).

Author: yajo

copier/main.py

@@ -74,18 +74,18 @@ class Worker:
     src_path: Optional[str] = None
     """String that can be resolved to a template path, be it local or remote.
 
-    See [Template.url][copier.template.Template.url] for more details.
+    See [Template.url][copier.template.Template.url].
 
-    If it is `None`, then it means that you are [updating a
-    project](../updating.md), and the original `src_path` will be obtained from
-    [the answers file](../configuring.md#the-answers-file).
+    If it is `None`, then it means that you are [updating a project][updating-a-project],
+    and the original `src_path` will be obtained from
+    [the answers file][the-copier-answersyml-file].
     """
 
     dst_path: Path = field(default=".")
     """Destination path where to render the subproject."""
 
     answers_file: Optional[RelativePath] = None
-    """Indicates the path for [the answers file](../configuring.md#the-answers-file).
+    """Indicates the path for [the answers file][the-copier-answersyml-file].
 
     The path must be relative to [dst_path][copier.main.Worker.dst_path].
 
@@ -102,38 +102,46 @@ class Worker:
     exclude: StrSeq = ()
     """Additional file exclusion patterns.
 
-    See [copier.template.Template.exclude][] for more details.
+    See [exclude][].
     """
 
     use_prereleases: bool = False
     """Consider prereleases when detecting the *latest* one?
 
-    See [copier.template.Template.use_prereleases][].
+    See [use_prereleases][].
 
     Useless if specifying a [vcs_ref][copier.main.Worker.vcs_ref].
     """
 
     skip_if_exists: StrSeq = ()
     """Additional file skip patterns.
 
-    See [copier.template.Template.skip_if_exists][] for more details.
+    See [skip_if_exists][].
     """
 
     cleanup_on_error: bool = True
     """Delete [dst_path][copier.main.Worker.dst_path] if there's an error?
 
-    It only applies when [dst_path][copier.main.Worker.dst_path] was created by
-    this process. Preexisting subprojects are never cleaned up.
+    See [cleanup_on_error][].
     """
 
     force: bool = False
-    """When `True`, disable all user interactions."""
+    """When `True`, disable all user interactions.
+
+    See [force][].
+    """
 
     pretend: bool = False
-    """When `True`, produce no real rendering."""
+    """When `True`, produce no real rendering.
+
+    See [pretend][].
+    """
 
     quiet: bool = False
-    """When `True`, disable all output."""
+    """When `True`, disable all output.
+
+    See [quiet][].
+    """
 
     def _answers_to_remember(self) -> Mapping:
         """Get only answers that will be remembered in the copier answers file."""
@@ -533,6 +541,8 @@ def run_copy(self) -> None:
         created. Otherwise, [src_path][copier.main.Worker.src_path] be rendered
         directly into it, without worrying about evolving what was there
         already.
+
+        See [generating a project][generating-a-project].
         """
         was_existing = self.subproject.local_abspath.exists()
         if not self.quiet:
@@ -559,20 +569,9 @@ def run_copy(self) -> None:
             print("")  # padding space
 
     def run_update(self) -> None:
-        """Update the subproject.
-
-        Before running this, [dst_path][copier.main.Worker.dst_path] must exist
-        and must contain an already-applied template, with a valid [copier
-        answers](../configuring.md#the-answers-file) file that points to a
-        versioned git template.
-
-        Copier will download the old template, render it with last answers,
-        download the latest version, apply it to the current subproject, and
-        compare both renders to apply a smart diff that, in practice, applies
-        the evolution of the template dynamically over the subproject.
+        """Update a subproject that was already generated.
 
-        In case of conflicts, `.rej` files will be dropped, next to the
-        conflicting ones.
+        See [updating a project][updating-a-project].
         """
         # Check all you need is there
         if self.subproject.vcs != "git":

copier/subproject.py

@@ -29,7 +29,7 @@ class Subproject:
     """Absolute path on local disk pointing to the subproject root folder."""
 
     answers_relpath: Path = Path(".copier-answers.yml")
-    """Relative path to [the answers file](../configuring.md#the-answers-file)."""
+    """Relative path to [the answers file][the-copier-answersyml-file]."""
 
     def is_dirty(self) -> bool:
         """Indicates if the local template root is dirty.

copier/template.py

@@ -73,7 +73,10 @@ def verify_minimum_version(version_str: str) -> None:
 
 @dataclass
 class Template:
-    """Object that represents a template and its current state."""
+    """Object that represents a template and its current state.
+
+    See [configuring a template][configuring-a-template].
+    """
 
     url: str
     """Absolute origin that points to the template.

copier/user_data.py

@@ -66,8 +66,8 @@ class AnswersMap:
     init: AnyByStrDict = field(default_factory=dict)
     """Answers provided on init.
 
-    This will hold those answers that come from `--data` in CLI mode, or
-    [copier.main.Worker.data][] in API mode.
+    This will hold those answers that come from `--data` in
+    CLI mode ([copier.main.Worker.data][] in API mode).
     """
 
     metadata: AnyByStrDict = field(default_factory=dict)
@@ -77,7 +77,13 @@ class AnswersMap:
     """
 
     last: AnyByStrDict = field(default_factory=dict)
+    """Data from [the answers file][the-copier-answersyml-file]."""
+
     default: AnyByStrDict = field(default_factory=dict)
+    """Default data from the template.
+
+    See [copier.template.Template.default_answers][].
+    """
 
     @cached_property
     def combined(self) -> t_ChainMap[str, Any]:
@@ -342,7 +348,7 @@ def load_yaml_data(conf_path: Path, quiet: bool = False) -> AnyByStrDict:
     """Load the `copier.yml` file.
 
     This is like a simple YAML load, but applying all specific quirks needed
-    for [the `copier.yml` file](../configuring.md#the-copieryml-file).
+    for [the `copier.yml` file][the-copieryml-file].
 
     For example, it supports the `!include` tag with glob includes, and
     merges multiple sections.

copier/vcs.py

@@ -10,8 +10,6 @@
 
 from .types import OptBool, OptStr, StrOrPath
 
-__all__ = ("get_repo", "clone")
-
 GIT_PREFIX = ("git@", "git://", "git+")
 GIT_POSTFIX = (".git",)
 REPLACEMENTS = (
@@ -40,6 +38,19 @@ def is_git_bundle(path: Path) -> bool:
 
 
 def get_repo(url: str) -> OptStr:
+    """Transforms `url` into a git-parseable origin URL.
+
+    Args:
+        url:
+            Valid examples:
+
+            - gh:copier-org/copier
+            - gl:copier-org/copier
+            - [email protected]:copier-org/copier.git
+            - git+https://mywebsiteisagitrepo.example.com/
+            - /local/path/to/git/repo
+            - /local/path/to/git/bundle/file.bundle
+    """
     for pattern, replacement in REPLACEMENTS:
         url = re.sub(pattern, replacement, url)
     url_path = Path(url)
@@ -86,6 +97,15 @@ def checkout_latest_tag(local_repo: StrOrPath, use_prereleases: OptBool = False)
 
 
 def clone(url: str, ref: OptStr = None) -> str:
+    """Clone repo into some temporary destination.
+
+    Args:
+        url:
+            Git-parseable URL of the repo. As returned by
+            [get_repo][copier.vcs.get_repo].
+        ref:
+            Reference to checkout. For Git repos, defaults to `HEAD`.
+    """
     location = tempfile.mkdtemp(prefix=f"{__name__}.clone.")
     git("clone", "--no-checkout", url, location)
     with local.cwd(location):

mkdocs.yml

@@ -41,6 +41,7 @@ markdown_extensions:
       permalink: true
 
 plugins:
+  - autorefs
   - search
   - mermaid2:
       arguments: