Resolve issues identified by the docs tests

Most issues boil down to "bad reference or typo".
Some were rendering differences between Sphinx 7.2
and the ancient Sphinx 1.8 version ReadTheDocs defaults to
when there isn't a `.readthedocs.yaml` file.

doc/source/api.rst

@@ -1,3 +1,4 @@
+:tocdepth: 2
 
 API
 ===

doc/source/conf.py

@@ -24,15 +24,15 @@
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-needs_sphinx = '1.2'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode']
 
+# The autodoc extension doesn't understand the `Self` typehint.
+# To avoid documentation build errors, autodoc typehints must be disabled.
+autodoc_typehints = "none"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -64,7 +64,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -102,7 +102,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -165,4 +165,4 @@
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

doc/source/index.rst

@@ -9,6 +9,7 @@ Welcome to pathspec's documentation!
 
 .. toctree::
    :caption: Contents:
+   :maxdepth: 2
 
    readme
    api

pathspec/gitignore.py

@@ -32,14 +32,14 @@
 
 class GitIgnoreSpec(PathSpec):
 	"""
-	The :class:`GitIgnoreSpec` class extends :class:`PathSpec` to
+	The :class:`GitIgnoreSpec` class extends :class:`pathspec.pathspec.PathSpec` to
 	replicate *.gitignore* behavior.
 	"""
 
 	def __eq__(self, other: object) -> bool:
 		"""
-		Tests the equality of this gitignore-spec with *other*
-		(:class:`GitIgnoreSpec`) by comparing their :attr:`~PathSpec.patterns`
+		Tests the equality of this gitignore-spec with *other* (:class:`GitIgnoreSpec`)
+		by comparing their :attr:`~pathspec.pattern.Pattern`
 		attributes. A non-:class:`GitIgnoreSpec` will not compare equal.
 		"""
 		if isinstance(other, GitIgnoreSpec):
@@ -66,7 +66,8 @@ def from_lines(
 		*pattern_factory* can be :data:`None`, the name of a registered
 		pattern factory (:class:`str`), or a :class:`~collections.abc.Callable`
 		used to compile patterns. The callable must accept an uncompiled
-		pattern (:class:`str`) and return the compiled pattern (:class:`.Pattern`).
+		pattern (:class:`str`) and return the compiled pattern
+		(:class:`pathspec.pattern.Pattern`).
 		Default is :data:`None` for :class:`.GitWildMatchPattern`).
 
 		Returns the :class:`GitIgnoreSpec` instance.

pathspec/pathspec.py

@@ -137,7 +137,7 @@ def match_entries(
 		"""
 		Matches the entries to this path-spec.
 
-		*entries* (:class:`~collections.abc.Iterable` of :class:`~util.TreeEntry`)
+		*entries* (:class:`~collections.abc.Iterable` of :class:`~pathspec.util.TreeEntry`)
 		contains the entries to be matched against :attr:`self.patterns <PathSpec.patterns>`.
 
 		*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
@@ -150,7 +150,7 @@ def match_entries(
 		:data:`False`.
 
 		Returns the matched entries (:class:`~collections.abc.Iterator` of
-		:class:`~util.TreeEntry`).
+		:class:`~pathspec.util.TreeEntry`).
 		"""
 		if not _is_iterable(entries):
 			raise TypeError(f"entries:{entries!r} is not an iterable.")
@@ -179,7 +179,7 @@ def match_file(
 		"""
 		Matches the file to this path-spec.
 
-		*file* (:class:`str` or :class:`os.PathLike[str]`) is the file path to be
+		*file* (:class:`str` or :class:`os.PathLike`) is the file path to be
 		matched against :attr:`self.patterns <PathSpec.patterns>`.
 
 		*separators* (:class:`~collections.abc.Collection` of :class:`str`)
@@ -202,7 +202,7 @@ def match_files(
 		Matches the files to this path-spec.
 
 		*files* (:class:`~collections.abc.Iterable` of :class:`str` or
-		:class:`os.PathLike[str]`) contains the file paths to be matched against
+		:class:`os.PathLike`) contains the file paths to be matched against
 		:attr:`self.patterns <PathSpec.patterns>`.
 
 		*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
@@ -215,7 +215,7 @@ def match_files(
 		:data:`False`.
 
 		Returns the matched files (:class:`~collections.abc.Iterator` of
-		:class:`str` or :class:`os.PathLike[str]`).
+		:class:`str` or :class:`os.PathLike`).
 		"""
 		if not _is_iterable(files):
 			raise TypeError(f"files:{files!r} is not an iterable.")
@@ -243,7 +243,7 @@ def match_tree_entries(
 		Walks the specified root path for all files and matches them to this
 		path-spec.
 
-		*root* (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
+		*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
 		search.
 
 		*on_error* (:class:`~collections.abc.Callable` or :data:`None`) optionally
@@ -277,7 +277,7 @@ def match_tree_files(
 		Walks the specified root path for all files and matches them to this
 		path-spec.
 
-		*root* (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
+		*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
 		search for files.
 
 		*on_error* (:class:`~collections.abc.Callable` or :data:`None`) optionally

pathspec/pattern.py

@@ -51,7 +51,7 @@ def match(self, files: Iterable[str]) -> Iterator[str]:
 
 		*files* (:class:`~collections.abc.Iterable` of :class:`str`)
 		contains each file relative to the root directory (e.g.,
-		:data:`"relative/path/to/file"`).
+		``"relative/path/to/file"``).
 
 		Returns an :class:`~collections.abc.Iterable` yielding each matched
 		file path (:class:`str`).
@@ -160,7 +160,7 @@ def match_file(self, file: str) -> Optional['RegexMatchResult']:
 		*file* (:class:`str`)
 		contains each file relative to the root directory (e.g., "relative/path/to/file").
 
-		Returns the match result (:class:`RegexMatchResult`) if *file*
+		Returns the match result (:class:`.RegexMatchResult`) if *file*
 		matched; otherwise, :data:`None`.
 		"""
 		if self.include is not None:

pathspec/util.py

@@ -62,7 +62,7 @@ def append_dir_sep(path: pathlib.Path) -> str:
 	files on the file-system by relying on the presence of a trailing path
 	separator.
 
-	*path* (:class:`pathlib.path`) is the path to use.
+	*path* (:class:`pathlib.Path`) is the path to use.
 
 	Returns the path (:class:`str`).
 	"""
@@ -88,7 +88,7 @@ def detailed_match_files(
 	*files* (:class:`~collections.abc.Iterable` of :class:`str`) contains
 	the normalized file paths to be matched against *patterns*.
 
-	*all_matches* (:class:`boot` or :data:`None`) is whether to return all
+	*all_matches* (:class:`bool` or :data:`None`) is whether to return all
 	matches patterns (:data:`True`), or only the last matched pattern
 	(:data:`False`). Default is :data:`None` for :data:`False`.
 
@@ -154,7 +154,7 @@ def iter_tree_entries(
 	"""
 	Walks the specified directory for all files and directories.
 
-	*root* (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
+	*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
 	search.
 
 	*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
@@ -270,7 +270,7 @@ def iter_tree_files(
 	"""
 	Walks the specified directory for all files.
 
-	*root* (:class:`str` or :class:`os.PathLike[str]`) is the root directory to
+	*root* (:class:`str` or :class:`os.PathLike`) is the root directory to
 	search for files.
 
 	*on_error* (:class:`~collections.abc.Callable` or :data:`None`)
@@ -376,16 +376,16 @@ def normalize_file(
 ) -> str:
 	"""
 	Normalizes the file path to use the POSIX path separator (i.e.,
-	:data:`'/'`), and make the paths relative (remove leading :data:`'/'`).
+	``"/"``), and make the paths relative (remove leading ``"/"``).
 
-	*file* (:class:`str` or :class:`os.PathLike[str]`) is the file path.
+	*file* (:class:`str` or :class:`os.PathLike`) is the file path.
 
 	*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
-	:data:`None`) optionally contains the path separators to normalize.
-	This does not need to include the POSIX path separator (:data:`'/'`),
-	but including it will not affect the results. Default is :data:`None`
-	for :data:`NORMALIZE_PATH_SEPS`. To prevent normalization, pass an
-	empty container (e.g., an empty tuple :data:`()`).
+	``None``) optionally contains the path separators to normalize.
+	This does not need to include the POSIX path separator (``"/"``),
+	but including it will not affect the results. Default is ``None``
+	for ``NORMALIZE_PATH_SEPS``. To prevent normalization, pass an
+	empty container (e.g., an empty tuple ``()``).
 
 	Returns the normalized file path (:class:`str`).
 	"""
@@ -421,15 +421,15 @@ def normalize_files(
 	Normalizes the file paths to use the POSIX path separator.
 
 	*files* (:class:`~collections.abc.Iterable` of :class:`str` or
-	:class:`os.PathLike[str]`) contains the file paths to be normalized.
+	:class:`os.PathLike`) contains the file paths to be normalized.
 
 	*separators* (:class:`~collections.abc.Collection` of :class:`str`; or
 	:data:`None`) optionally contains the path separators to normalize.
 	See :func:`normalize_file` for more information.
 
 	Returns a :class:`dict` mapping each normalized file path (:class:`str`)
 	to the original file paths (:class:`list` of :class:`str` or
-	:class:`os.PathLike[str]`).
+	:class:`os.PathLike`).
 	"""
 	warnings.warn((
 		"util.normalize_files() is deprecated. Use util.normalize_file() "