Find all document files in the source directory and put them in :attr:`docnames`.
(
self, exclude_paths: Iterable[str] = (), include_paths: Iterable[str] = ('**',)
)
| 47 | self._docname_to_path = other._docname_to_path |
| 48 | |
| 49 | def discover( |
| 50 | self, exclude_paths: Iterable[str] = (), include_paths: Iterable[str] = ('**',) |
| 51 | ) -> set[str]: |
| 52 | """Find all document files in the source directory and put them in |
| 53 | :attr:`docnames`. |
| 54 | """ |
| 55 | self.docnames.clear() |
| 56 | self._path_to_docname.clear() |
| 57 | self._docname_to_path.clear() |
| 58 | |
| 59 | for filename in get_matching_files( |
| 60 | self.srcdir, |
| 61 | include_paths, |
| 62 | [*exclude_paths, *EXCLUDE_PATHS], |
| 63 | ): |
| 64 | if docname := self.path2doc(filename): |
| 65 | if docname in self.docnames: |
| 66 | files = [ |
| 67 | str(f.relative_to(self.srcdir)) |
| 68 | for f in self.srcdir.glob(f'{docname}.*') |
| 69 | ] |
| 70 | logger.warning( |
| 71 | __( |
| 72 | 'multiple files found for the document "%s": %s\n' |
| 73 | 'Use %r for the build.' |
| 74 | ), |
| 75 | docname, |
| 76 | ', '.join(files), |
| 77 | self.doc2path(docname, absolute=True), |
| 78 | once=True, |
| 79 | ) |
| 80 | elif os.access(self.srcdir / filename, os.R_OK): |
| 81 | self.docnames.add(docname) |
| 82 | path = Path(filename) |
| 83 | self._path_to_docname[path] = docname |
| 84 | self._docname_to_path[docname] = path |
| 85 | else: |
| 86 | logger.warning( |
| 87 | __('Ignored unreadable document %r.'), |
| 88 | filename, |
| 89 | location=docname, |
| 90 | ) |
| 91 | |
| 92 | return self.docnames |
| 93 | |
| 94 | def path2doc(self, filename: str | os.PathLike[str]) -> str | None: |
| 95 | """Return the docname for the filename if the file is a document. |