Read the doctree from the pickle, resolve cross-references and toctrees and return it.
(
self,
docname: str,
builder: Builder,
*,
tags: Tags = ..., # type: ignore[assignment]
doctree: nodes.document | None = None,
prune_toctrees: bool = True,
includehidden: bool = False,
)
| 666 | return self.get_doctree(self.config.root_doc) |
| 667 | |
| 668 | def get_and_resolve_doctree( |
| 669 | self, |
| 670 | docname: str, |
| 671 | builder: Builder, |
| 672 | *, |
| 673 | tags: Tags = ..., # type: ignore[assignment] |
| 674 | doctree: nodes.document | None = None, |
| 675 | prune_toctrees: bool = True, |
| 676 | includehidden: bool = False, |
| 677 | ) -> nodes.document: |
| 678 | """Read the doctree from the pickle, resolve cross-references and |
| 679 | toctrees and return it. |
| 680 | """ |
| 681 | if tags is ...: |
| 682 | warnings.warn( |
| 683 | "'tags' will become a required keyword argument " |
| 684 | 'for global_toctree_for_doc() in Sphinx 11.0.', |
| 685 | RemovedInSphinx11Warning, |
| 686 | stacklevel=2, |
| 687 | ) |
| 688 | tags = builder.tags |
| 689 | |
| 690 | if doctree is None: |
| 691 | try: |
| 692 | doctree = self._write_doc_doctree_cache.pop(docname) |
| 693 | doctree.settings.env = self |
| 694 | doctree.reporter = LoggingReporter(str(self.doc2path(docname))) |
| 695 | except KeyError: |
| 696 | doctree = self.get_doctree(docname) |
| 697 | |
| 698 | # resolve all pending cross-references |
| 699 | self.apply_post_transforms(doctree, docname) |
| 700 | |
| 701 | # now, resolve all toctree nodes |
| 702 | for toctreenode in doctree.findall(addnodes.toctree): |
| 703 | result = toctree_adapters._resolve_toctree( |
| 704 | self, |
| 705 | docname, |
| 706 | builder, |
| 707 | toctreenode, |
| 708 | prune=prune_toctrees, |
| 709 | includehidden=includehidden, |
| 710 | tags=tags, |
| 711 | ) |
| 712 | if result is None: |
| 713 | toctreenode.parent.replace(toctreenode, []) |
| 714 | else: |
| 715 | toctreenode.replace_self(result) |
| 716 | |
| 717 | return doctree |
| 718 | |
| 719 | def resolve_toctree( |
| 720 | self, |