1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
"""Utility function and classes for Sphinx projects."""
from __future__ import annotations
import contextlib
import os
from glob import glob
from typing import TYPE_CHECKING
from sphinx.locale import __
from sphinx.util import logging
from sphinx.util.matching import get_matching_files
from sphinx.util.osutil import path_stabilize, relpath
if TYPE_CHECKING:
from collections.abc import Iterable
logger = logging.getLogger(__name__)
EXCLUDE_PATHS = ['**/_sources', '.#*', '**/.#*', '*.lproj/**']
class Project:
"""A project is the source code set of the Sphinx document(s)."""
def __init__(self, srcdir: str | os.PathLike[str], source_suffix: Iterable[str]) -> None:
#: Source directory.
self.srcdir = srcdir
#: source_suffix. Same as :confval:`source_suffix`.
self.source_suffix = tuple(source_suffix)
self._first_source_suffix = next(iter(self.source_suffix), "")
#: The name of documents belonging to this project.
self.docnames: set[str] = set()
# Bijective mapping between docnames and (srcdir relative) paths.
self._path_to_docname: dict[str, str] = {}
self._docname_to_path: dict[str, str] = {}
def restore(self, other: Project) -> None:
"""Take over a result of last build."""
self.docnames = other.docnames
self._path_to_docname = other._path_to_docname
self._docname_to_path = other._docname_to_path
def discover(self, exclude_paths: Iterable[str] = (),
include_paths: Iterable[str] = ("**",)) -> set[str]:
"""Find all document files in the source directory and put them in
:attr:`docnames`.
"""
self.docnames.clear()
self._path_to_docname.clear()
self._docname_to_path.clear()
for filename in get_matching_files(
self.srcdir,
include_paths,
[*exclude_paths] + EXCLUDE_PATHS,
):
if docname := self.path2doc(filename):
if docname in self.docnames:
pattern = os.path.join(self.srcdir, docname) + '.*'
files = [relpath(f, self.srcdir) for f in glob(pattern)]
logger.warning(__('multiple files found for the document "%s": %r\n'
'Use %r for the build.'),
docname, files, self.doc2path(docname, absolute=True),
once=True)
elif os.access(os.path.join(self.srcdir, filename), os.R_OK):
self.docnames.add(docname)
self._path_to_docname[filename] = docname
self._docname_to_path[docname] = filename
else:
logger.warning(__("Ignored unreadable document %r."),
filename, location=docname)
return self.docnames
def path2doc(self, filename: str | os.PathLike[str]) -> str | None:
"""Return the docname for the filename if the file is a document.
*filename* should be absolute or relative to the source directory.
"""
try:
return self._path_to_docname[filename] # type: ignore[index]
except KeyError:
if os.path.isabs(filename):
with contextlib.suppress(ValueError):
filename = os.path.relpath(filename, self.srcdir)
for suffix in self.source_suffix:
if os.path.basename(filename).endswith(suffix):
return path_stabilize(filename).removesuffix(suffix)
# the file does not have a docname
return None
def doc2path(self, docname: str, absolute: bool) -> str:
"""Return the filename for the document name.
If *absolute* is True, return as an absolute path.
Else, return as a relative path to the source directory.
"""
try:
filename = self._docname_to_path[docname]
except KeyError:
# Backwards compatibility: the document does not exist
filename = docname + self._first_source_suffix
if absolute:
return os.path.join(self.srcdir, filename)
return filename
|
