Parse a file and add/update inventory entries for the doctree.
(self, docname: str, *, _cache: bool = True)
| 630 | |
| 631 | @final |
| 632 | def read_doc(self, docname: str, *, _cache: bool = True) -> None: |
| 633 | """Parse a file and add/update inventory entries for the doctree.""" |
| 634 | env = self.env |
| 635 | env.prepare_settings(docname) |
| 636 | |
| 637 | # Add confdir/docutils.conf to dependencies list if exists |
| 638 | docutils_conf = self.confdir / 'docutils.conf' |
| 639 | if docutils_conf.is_file(): |
| 640 | env.note_dependency(docutils_conf) |
| 641 | |
| 642 | filename = env.doc2path(docname) |
| 643 | |
| 644 | # read the source file |
| 645 | content = filename.read_text(encoding=env.settings['input_encoding']) |
| 646 | |
| 647 | # TODO: move the "source-read" event to here. |
| 648 | |
| 649 | filetype = get_filetype(self.config.source_suffix, filename) |
| 650 | parser = self._registry.create_source_parser( |
| 651 | filetype, config=self.config, env=env |
| 652 | ) |
| 653 | doctree = _parse_str_to_doctree( |
| 654 | content, |
| 655 | filename=filename, |
| 656 | default_role=self.config.default_role, |
| 657 | default_settings=env.settings, |
| 658 | env=env, |
| 659 | events=self.events, |
| 660 | parser=parser, |
| 661 | transforms=self._registry.get_transforms(), |
| 662 | ) |
| 663 | |
| 664 | # store time of reading, for outdated files detection |
| 665 | env.all_docs[docname] = time.time_ns() // 1_000 |
| 666 | |
| 667 | # cleanup |
| 668 | env.current_document = _CurrentDocument() |
| 669 | env.ref_context.clear() |
| 670 | |
| 671 | self.write_doctree(docname, doctree, _cache=_cache) |
| 672 | |
| 673 | @final |
| 674 | def write_doctree( |
no test coverage detected