sphinx.builders._epub_base.EpubBuilder

class documentation

class EpubBuilder(StandaloneHTMLBuilder):

Known subclasses: sphinx.builders.epub3.Epub3Builder

Builder that outputs epub files.

It creates the metainfo files container.opf, toc.ncx, mimetype, and META-INF/container.xml. Afterwards, all necessary files are zipped to an epub file.

Method	`add_visible_links`	Add visible link targets for external links
Method	`build_container`	Write the metainfo file META-INF/container.xml.
Method	`build_content`	Write the metainfo file content.opf It contains bibliographic data, a file list and the spine (the reading order).
Method	`build_epub`	Write the epub file.
Method	`build_mimetype`	Write the metainfo file mimetype.
Method	`build_navpoints`	Create the toc navigation structure.
Method	`build_toc`	Write the metainfo file toc.ncx.
Method	`check_refnodes`	Undocumented
Method	`content_metadata`	Create a dictionary with all metadata for the content.opf file properly escaped.
Method	`copy_download_files`	Undocumented
Method	`copy_image_files`	Copy image files to destination directory. This overwritten method can use Pillow to convert image files.
Method	`copy_image_files_pil`	Copy images using Pillow, the Python Imaging Library. The method tries to read and write the files with Pillow, converting the format and resizing the image if necessary/possible.
Method	`create_build_info`	Undocumented
Method	`fix_fragment`	Return a href/id attribute with colons replaced by hyphens.
Method	`fix_genindex`	Fix href attributes for genindex pages.
Method	`fix_ids`	Replace colons with hyphens in href and id attributes.
Method	`get_refnodes`	Collect section titles, their depth in the toc and the refuri.
Method	`get_theme_config`	Undocumented
Method	`get_toc`	Get the total table of contents, containing the root_doc and pre and post files not managed by sphinx.
Method	`handle_page`	Create a rendered page.
Method	`init`	Load necessary templates and perform initialization. The default implementation does nothing.
Method	`is_vector_graphics`	Does the filename extension indicate a vector graphic format?
Method	`make_id`	Return a unique id for name.
Method	`new_navpoint`	Create a new entry in the toc from the node at given level.
Method	`toc_add_files`	Add the root_doc, pre and post files to a list of refnodes.
Method	`toc_metadata`	Create a dictionary with all metadata for the toc.ncx file properly escaped.
Method	`write_doc`	Write one document file.
Class Variable	`add_permalinks`	Undocumented
Class Variable	`allow_sharp_as_current_path`	Undocumented
Class Variable	`copysource`	Undocumented
Class Variable	`doctype`	Undocumented
Class Variable	`download_support`	Undocumented
Class Variable	`embedded`	Undocumented
Class Variable	`html_scaled_image_link`	Undocumented
Class Variable	`search`	Undocumented
Class Variable	`supported_image_types`	Undocumented
Class Variable	`supported_remote_images`	Undocumented
Class Variable	`template_dir`	Undocumented
Instance Variable	`files`	Undocumented
Instance Variable	`id_cache`	Undocumented
Instance Variable	`ignored_files`	Undocumented
Instance Variable	`link_suffix`	Undocumented
Instance Variable	`out_suffix`	Undocumented
Instance Variable	`playorder`	Undocumented
Instance Variable	`refnodes`	Undocumented
Instance Variable	`tocid`	Undocumented
Instance Variable	`use_index`	Undocumented

Inherited from StandaloneHTMLBuilder:

Class Variable	`format`	Undocumented
Class Variable	`name`	Undocumented
Method	`__init__`	Undocumented
Method	`_get_local_toctree`	Undocumented
Method	`_get_style_filename`	Undocumented
Method	`_get_translations_js`	Undocumented
Method	`add_css_file`	Undocumented
Method	`add_js_file`	Undocumented
Method	`add_sidebars`	Undocumented
Method	`cleanup`	Cleanup any resources.
Method	`copy_extra_files`	copy html_extra_path files.
Method	`copy_html_favicon`	Undocumented
Method	`copy_html_logo`	Undocumented
Method	`copy_html_static_files`	Undocumented
Method	`copy_static_files`	Undocumented
Method	`copy_stemmer_js`	Copy a JavaScript file for stemmer.
Method	`copy_theme_static_files`	Undocumented
Method	`copy_translation_js`	Copy a JavaScript file for translations.
Method	`create_pygments_style_file`	create a style file for pygments.
Method	`dump_inventory`	Undocumented
Method	`dump_search_index`	Undocumented
Method	`finish`	Finish the building process.
Method	`gen_additional_pages`	Undocumented
Method	`gen_indices`	Undocumented
Method	`gen_pages_from_extensions`	Undocumented
Method	`get_asset_paths`	Return list of paths for assets (ex. templates, CSS, etc.).
Method	`get_doc_context`	Collect items for the template context of a page.
Method	`get_outdated_docs`	Return an iterable of output files that are outdated, or a string describing what an update build will build.
Method	`get_outfilename`	Undocumented
Method	`get_target_uri`	Return the target URI for a document name.
Method	`handle_finish`	Undocumented
Method	`index_page`	Undocumented
Method	`init_css_files`	Undocumented
Method	`init_highlighter`	Undocumented
Method	`init_js_files`	Undocumented
Method	`init_templates`	Undocumented
Method	`load_indexer`	Undocumented
Method	`post_process_images`	Pick the best candidate for an image and link down-scaled images to their high res version.
Method	`prepare_writing`	A place where you can add logic before `write_doc` is run
Method	`render_partial`	Utility: Render a lone doctree node.
Method	`update_page_context`	Undocumented
Method	`write_buildinfo`	Undocumented
Method	`write_doc_serialized`	Handle parts of write_doc that must be called in the main process if parallel build is active.
Method	`write_domain_indices`	Undocumented
Method	`write_genindex`	Undocumented
Class Variable	`allow_parallel`	Undocumented
Class Variable	`epilog`	Undocumented
Class Variable	`indexer_dumps_unicode`	Undocumented
Class Variable	`searchindex_filename`	Undocumented
Class Variable	`supported_data_uri_images`	Undocumented
Instance Variable	`_css_files`	Undocumented
Instance Variable	`_script_files`	Undocumented
Instance Variable	`build_info`	Undocumented
Instance Variable	`css_files`	Undocumented
Instance Variable	`current_docname`	Undocumented
Instance Variable	`dark_highlighter`	Undocumented
Instance Variable	`dlpath`	Undocumented
Instance Variable	`docsettings`	Undocumented
Instance Variable	`docwriter`	Undocumented
Instance Variable	`domain_indices`	Undocumented
Instance Variable	`fignumbers`	Undocumented
Instance Variable	`globalcontext`	Undocumented
Instance Variable	`highlighter`	Undocumented
Instance Variable	`imagedir`	Undocumented
Instance Variable	`imgpath`	Undocumented
Instance Variable	`indexer`	Undocumented
Instance Variable	`last_updated`	Undocumented
Instance Variable	`relations`	Undocumented
Instance Variable	`script_files`	Undocumented
Instance Variable	`secnumbers`	Undocumented
Instance Variable	`theme`	Undocumented
Instance Variable	`theme_options`	Undocumented
Property	`default_translator_class`	Undocumented
Property	`math_renderer_name`	Undocumented

Inherited from Builder (via StandaloneHTMLBuilder):

Method	`build`	Main build method.
Method	`build_all`	Build all source files.
Method	`build_specific`	Only rebuild as much as needed for changes in the filenames.
Method	`build_update`	Only rebuild what was changed or added since last build.
Method	`get_relative_uri`	Return a relative URI between two source filenames.
Instance Variable	`events`	Undocumented
Method	`_read_parallel`	Undocumented
Method	`_read_serial`	Undocumented
Method	`_write_parallel`	Undocumented
Method	`_write_serial`	Undocumented
Method	`compile_all_catalogs`	Undocumented
Method	`compile_catalogs`	Undocumented
Method	`compile_specific_catalogs`	Undocumented
Method	`compile_update_catalogs`	Undocumented
Method	`create_template_bridge`	Return the template bridge configured.
Method	`create_translator`	Return an instance of translator.
Method	`get_builder_config`	Return a builder specific option.
Method	`get_translator_class`	Return a class of translator.
Method	`read`	(Re-)read all files new or changed since last update.
Method	`read_doc`	Parse a file and add/update inventory entries for the doctree.
Method	`set_environment`	Store BuildEnvironment object.
Method	`write`	Undocumented
Method	`write_doctree`	Write the doctree to a file.
Class Variable	`use_message_catalog`	Undocumented
Class Variable	`versioning_compare`	Undocumented
Class Variable	`versioning_method`	Undocumented
Instance Variable	`app`	Undocumented
Instance Variable	`confdir`	Undocumented
Instance Variable	`config`	Undocumented
Instance Variable	`doctreedir`	Undocumented
Instance Variable	`env`	Undocumented
Instance Variable	`finish_tasks`	Undocumented
Instance Variable	`images`	Undocumented
Instance Variable	`outdir`	Undocumented
Instance Variable	`parallel_ok`	Undocumented
Instance Variable	`srcdir`	Undocumented
Instance Variable	`tags`	Undocumented
Instance Variable	`templates`	Undocumented

def add_visible_links(self, tree, show_urls='inline'):

Add visible link targets for external links

Parameters
tree:`nodes.document`	Undocumented
show_urls:`str`	Undocumented

def build_container(self, outname='META-INF/container.xml'):

Write the metainfo file META-INF/container.xml.

Parameters
outname:`str`	Undocumented

def build_content(self):

Write the metainfo file content.opf It contains bibliographic data, a file list and the spine (the reading order).

def build_epub(self):

Write the epub file.

It is a zip file with the mimetype file stored uncompressed as the first entry.

def build_mimetype(self):

Write the metainfo file mimetype.

def build_navpoints(self, nodes):

Create the toc navigation structure.

Subelements of a node are nested inside the navpoint. For nested nodes the parent node is reinserted in the subnav.

Parameters
nodes:`List[Dict[str, Any]]`	Undocumented
Returns
`List[NavPoint]`	Undocumented

def build_toc(self):

Write the metainfo file toc.ncx.

def check_refnodes(self, nodes):

Undocumented

Parameters
nodes:`List[Dict[str, Any]]`	Undocumented

def content_metadata(self):

overridden in sphinx.builders.epub3.Epub3Builder

Create a dictionary with all metadata for the content.opf file properly escaped.

Returns
`Dict[str, Any]`	Undocumented

def copy_download_files(self):

overrides sphinx.builders.html.StandaloneHTMLBuilder.copy_download_files

Undocumented

def copy_image_files(self):

overrides sphinx.builders.html.StandaloneHTMLBuilder.copy_image_files

Copy image files to destination directory. This overwritten method can use Pillow to convert image files.

def copy_image_files_pil(self):

Copy images using Pillow, the Python Imaging Library. The method tries to read and write the files with Pillow, converting the format and resizing the image if necessary/possible.

def create_build_info(self):

overrides sphinx.builders.html.StandaloneHTMLBuilder.create_build_info

Undocumented

Returns
`BuildInfo`	Undocumented

def fix_fragment(self, prefix, fragment):

Return a href/id attribute with colons replaced by hyphens.

Parameters
prefix:`str`	Undocumented
fragment:`str`	Undocumented
Returns
`str`	Undocumented

def fix_genindex(self, tree):

Fix href attributes for genindex pages.

Parameters
tree:`List[Tuple[str, List[Tuple[str, Any]]]]`	Undocumented

def fix_ids(self, tree):

Replace colons with hyphens in href and id attributes.

Some readers crash because they interpret the part as a transport protocol specification.

Parameters
tree:`nodes.document`	Undocumented

def get_refnodes(self, doctree, result):

Collect section titles, their depth in the toc and the refuri.

Parameters
doctree:`Node`	Undocumented
result:`List[Dict[str, Any]]`	Undocumented
Returns
`List[Dict[str, Any]]`	Undocumented

def get_theme_config(self):

overrides sphinx.builders.html.StandaloneHTMLBuilder.get_theme_config

Undocumented

Returns
`Tuple[str, Dict]`	Undocumented

def get_toc(self):

Get the total table of contents, containing the root_doc and pre and post files not managed by sphinx.

def handle_page(self, pagename, addctx, templatename='page.html', outfilename=None, event_arg=None):

overrides sphinx.builders.html.StandaloneHTMLBuilder.handle_page

Create a rendered page.

This method is overwritten for genindex pages in order to fix href link attributes.

Parameters
pagename:`str`	Undocumented
addctx:`Dict`	Undocumented
templatename:`str`	Undocumented
outfilename:`str`	Undocumented
event_arg:`Any`	Undocumented

def init(self):

overrides sphinx.builders.html.StandaloneHTMLBuilder.init

Load necessary templates and perform initialization. The default implementation does nothing.

def is_vector_graphics(self, filename):

Does the filename extension indicate a vector graphic format?

Parameters
filename:`str`	Undocumented
Returns
`bool`	Undocumented

def make_id(self, name):

Return a unique id for name.

Parameters
name:`str`	Undocumented
Returns
`str`	Undocumented

def new_navpoint(self, node, level, incr=True):

Create a new entry in the toc from the node at given level.

Parameters
node:`Dict[str, Any]`	Undocumented
level:`int`	Undocumented
incr:`bool`	Undocumented
Returns
`NavPoint`	Undocumented

def toc_add_files(self, refnodes):

Add the root_doc, pre and post files to a list of refnodes.

Parameters
refnodes:`List[Dict[str, Any]]`	Undocumented

def toc_metadata(self, level, navpoints):

Create a dictionary with all metadata for the toc.ncx file properly escaped.

Parameters
level:`int`	Undocumented
navpoints:`List[NavPoint]`	Undocumented
Returns
`Dict[str, Any]`	Undocumented

def write_doc(self, docname, doctree):

overrides sphinx.builders.html.StandaloneHTMLBuilder.write_doc

Write one document file.

This method is overwritten in order to fix fragment identifiers and to add visible external links.

Parameters
docname:`str`	Undocumented
doctree:`nodes.document`	Undocumented

add_permalinks: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.add_permalinks

Undocumented

allow_sharp_as_current_path: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.allow_sharp_as_current_path

Undocumented

copysource: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.copysource

Undocumented

doctype: str =

Undocumented

download_support: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.download_support

Undocumented

embedded: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.embedded

Undocumented

html_scaled_image_link: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.html_scaled_image_link

Undocumented

search: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.search

Undocumented

supported_image_types: list[str] =

overrides sphinx.builders.html.StandaloneHTMLBuilder.supported_image_types

Undocumented

supported_remote_images: bool =

overrides sphinx.builders.html.StandaloneHTMLBuilder.supported_remote_images

overridden in sphinx.builders.epub3.Epub3Builder

Undocumented

template_dir: str =

overridden in sphinx.builders.epub3.Epub3Builder

Undocumented

files: List[str] =

Undocumented

id_cache: Dict[str, str] =

Undocumented

ignored_files =

Undocumented

link_suffix: str =

overrides sphinx.builders.html.StandaloneHTMLBuilder.link_suffix

Undocumented

out_suffix: str =

overrides sphinx.builders.html.StandaloneHTMLBuilder.out_suffix

Undocumented

playorder: int =

Undocumented

refnodes =

Undocumented

tocid: int =

Undocumented

use_index =

overrides sphinx.builders.html.StandaloneHTMLBuilder.use_index

Undocumented