Method write

sphinx/builders/__init__.py:705–748

Write builder specific output files.

(
        self,
        build_docnames: Iterable[str] | None,
        updated_docnames: Iterable[str],
        method: Literal['all', 'specific', 'update'] = 'update',
    )

    @final
    def write(
        self,
        build_docnames: Iterable[str] | None,
        updated_docnames: Iterable[str],
        method: Literal['all', 'specific', 'update'] = 'update',
    ) -> None:
        """Write builder specific output files."""
        env = self.env

        # Allow any extensions to perform setup for writing
        self.events.emit('write-started', self)

        if build_docnames is None or build_docnames == ['__all__']:
            # build_all
            build_docnames = env.found_docs
        if method == 'update':
            # build updated ones as well
            docnames = set(build_docnames) | set(updated_docnames)
        else:
            docnames = set(build_docnames)
        if docnames:
            logger.debug(__('docnames to write: %s'), ', '.join(sorted(docnames)))
        else:
            logger.debug(__('no docnames to write!'))

        # add all toctree-containing files that may have changed
        docnames |= {
            toc_docname
            for docname in docnames
            for toc_docname in env.files_to_rebuild.get(docname, ())
            if toc_docname in env.found_docs
        }

        # sort to ensure deterministic toctree generation
        env.toctree_includes = dict(sorted(env.toctree_includes.items()))

        with progress_message(__('preparing documents')):
            self.prepare_writing(docnames)

        with progress_message(__('copying assets'), nonl=False):
            self.copy_assets()

        if docnames:
            self.write_documents(docnames)

    def write_documents(self, docnames: Set[str]) -> None:
        """Write all documents in *docnames*.