Write the doctree to a file, to be used as a cache by re-builds.
(
self,
docname: str,
doctree: nodes.document,
*,
_cache: bool = True,
)
| 672 | |
| 673 | @final |
| 674 | def write_doctree( |
| 675 | self, |
| 676 | docname: str, |
| 677 | doctree: nodes.document, |
| 678 | *, |
| 679 | _cache: bool = True, |
| 680 | ) -> None: |
| 681 | """Write the doctree to a file, to be used as a cache by re-builds.""" |
| 682 | # make it pickleable |
| 683 | doctree.reporter = None # type: ignore[assignment] |
| 684 | doctree.transformer = None # type: ignore[assignment] |
| 685 | |
| 686 | # Create a copy of settings object before modification because it is |
| 687 | # shared with other documents. |
| 688 | doctree.settings = doctree.settings.copy() |
| 689 | doctree.settings.warning_stream = None |
| 690 | doctree.settings.env = None |
| 691 | doctree.settings.record_dependencies = DependencyList() |
| 692 | |
| 693 | doctree_filename = self.doctreedir / f'{docname}.doctree' |
| 694 | doctree_filename.parent.mkdir(parents=True, exist_ok=True) |
| 695 | with open(doctree_filename, 'wb') as f: |
| 696 | pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) |
| 697 | |
| 698 | # When Sphinx is running in parallel mode, ``write_doctree()`` is invoked |
| 699 | # in the context of a process worker, and thus it does not make sense to |
| 700 | # pickle the doctree and send it to the main process |
| 701 | if _cache: |
| 702 | self.env._write_doc_doctree_cache[docname] = doctree |
| 703 | |
| 704 | @final |
| 705 | def write( |