def _process_root_document(self):
docname = self.config.master_doc
# Extract the title from the root document as it will be used to decide
# which Confluence page the document will be published to.
if (self.config.confluence_title_overrides
and docname in self.config.confluence_title_overrides):
doctitle = self.config.confluence_title_overrides[docname]
else:
doctree = self.env.get_doctree(docname)
doctitle = self._parse_doctree_title(docname, doctree)
if not doctitle:
return None
# register the title for the root document (for references, assets, ...)
ConfluenceState.registerTitle(docname, doctitle, self.config)
# register the root document for publishing
self.publish_docnames.append(docname)
return doctitle
def prepare_writing(self, docnames):
ordered_docnames = []
traversed = [self.config.master_doc]
# prepare caching doctree hook
#
# We'll temporarily override the environment's 'get_doctree' method to
# allow this extension to manipulate the doctree for a document inside
# the pre-writing stage to also take effect in the writing stage.
self._original_get_doctree = self.env.get_doctree
self.env.get_doctree = self._get_doctree
# process the document structure of the master document, allowing:
# - populating a publish order to ensure parent pages are created first
# (when using hierarchy mode)
# - squash pages which exceed maximum depth (if configured with a max
# depth value)
self.process_tree_structure(ordered_docnames, self.config.master_doc,
traversed)
# track relations between accepted documents
#
# Prepares a relation mapping between each non-orphan documents which
# can be used by navigational elements.
prevdoc = ordered_docnames[0] if ordered_docnames else None
for docname in ordered_docnames[1:]:
self.nav_prev[docname] = self.get_relative_uri(docname, prevdoc)
self.nav_next[prevdoc] = self.get_relative_uri(prevdoc, docname)
prevdoc = docname
# add orphans (if any) to the publish list
ordered_docnames.extend(x for x in docnames if x not in traversed)
for docname in ordered_docnames:
doctree = self.env.get_doctree(docname)
# acquire title from override (if any), or parse first title entity
if (self.config.confluence_title_overrides
and docname in self.config.confluence_title_overrides):
doctitle = self.config.confluence_title_overrides[docname]
else:
doctitle = self._parse_doctree_title(docname, doctree)
# only register title/track for publishing if there is a title
# value that can be applied to this document
if doctitle:
secnumbers = self.env.toc_secnumbers.get(docname, {})
if self.add_secnumbers and secnumbers.get(''):
doctitle = ('.'.join(map(str, secnumbers[''])) +
self.secnumber_suffix + doctitle)
doctitle = ConfluenceState.registerTitle(
docname, doctitle, self.config)
# only publish documents that sphinx asked to prepare
if docname in docnames:
self.publish_docnames.append(docname)
# track the toctree depth for a document, which a translator can
# use as a hint when dealing with max-depth capabilities
toctree = first(doctree.traverse(addnodes.toctree))
if toctree and toctree.get('maxdepth') > 0:
ConfluenceState.registerToctreeDepth(docname,
toctree.get('maxdepth'))
# register title targets for references
self._register_doctree_title_targets(docname, doctree)
# post-prepare a ready doctree
self._prepare_doctree_writing(docname, doctree)
# Scan for assets that may exist in the documents to be published. This
# will find most if not all assets in the documentation set. The
# exception is assets which may be finalized during a document's post
# transformation stage (e.g. embedded images are converted into real
# images in Sphinx, which is then provided to a translator). Embedded
# images are detected during an 'doctree-resolved' hook (see __init__).
self.assets.process(ordered_docnames)