sphinx.builders._epub_base.EpubBuilder

class documentation

class EpubBuilder(StandaloneHTMLBuilder): (source)

Known subclasses: sphinx.builders.epub3.Epub3Builder

View In Hierarchy

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:

Method __init__ 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 :meth:`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 format Undocumented
Class Variable indexer_dumps_unicode Undocumented
Class Variable name Undocumented
Class Variable searchindex_filename Undocumented
Class Variable supported_data_uri_images 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
Method _get_local_toctree Undocumented
Method _get_style_filenames Undocumented
Method _get_translations_js Undocumented
Instance Variable _css_files Undocumented
Instance Variable _publisher Undocumented
Instance Variable _script_files 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 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_relative_uri Return a relative URI between two source filenames.
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 events 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
Method _read_parallel Undocumented
Method _read_serial Undocumented
Method _write_parallel Undocumented
Method _write_serial Undocumented
def add_visible_links(self, tree, show_urls='inline'): (source)

Add visible link targets for external links

Parameters
tree:nodes.documentUndocumented
show_urls:strUndocumented
def build_container(self, outname='META-INF/container.xml'): (source)

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

Parameters
outname:strUndocumented
def build_content(self): (source)

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

def build_epub(self): (source)

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

def build_mimetype(self): (source)

Write the metainfo file mimetype.

def build_navpoints(self, nodes): (source)

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): (source)

Write the metainfo file toc.ncx.

def check_refnodes(self, nodes): (source)

Undocumented

Parameters
nodes:list[dict[str, Any]]Undocumented
def content_metadata(self): (source)
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): (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.copy_download_files

Undocumented

def copy_image_files(self): (source)
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): (source)

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): (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.create_build_info

Undocumented

Returns
BuildInfoUndocumented
def fix_fragment(self, prefix, fragment): (source)

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

Parameters
prefix:strUndocumented
fragment:strUndocumented
Returns
strUndocumented
def fix_genindex(self, tree): (source)

Fix href attributes for genindex pages.

Parameters
tree:list[tuple[str, list[tuple[str, Any]]]]Undocumented
def fix_ids(self, tree): (source)

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.documentUndocumented
def get_refnodes(self, doctree, result): (source)

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

Parameters
doctree:NodeUndocumented
result:list[dict[str, Any]]Undocumented
Returns
list[dict[str, Any]]Undocumented
def get_theme_config(self): (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.get_theme_config

Undocumented

Returns
tuple[str, dict]Undocumented
def get_toc(self): (source)

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): (source)
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:strUndocumented
addctx:dictUndocumented
templatename:strUndocumented
outfilename:str|NoneUndocumented
event_arg:AnyUndocumented
def init(self): (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.init

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

def is_vector_graphics(self, filename): (source)

Does the filename extension indicate a vector graphic format?

Parameters
filename:strUndocumented
Returns
boolUndocumented
def make_id(self, name): (source)

Return a unique id for name.

Parameters
name:strUndocumented
Returns
strUndocumented
def new_navpoint(self, node, level, incr=True): (source)

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

Parameters
node:dict[str, Any]Undocumented
level:intUndocumented
incr:boolUndocumented
Returns
NavPointUndocumented
def toc_add_files(self, refnodes): (source)

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): (source)

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

Parameters
level:intUndocumented
navpoints:list[NavPoint]Undocumented
Returns
dict[str, Any]Undocumented
def write_doc(self, docname, doctree): (source)
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:strUndocumented
doctree:nodes.documentUndocumented
add_permalinks: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.add_permalinks

Undocumented

allow_sharp_as_current_path: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.allow_sharp_as_current_path

Undocumented

copysource: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.copysource

Undocumented

doctype: str = (source)

Undocumented

download_support: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.download_support

Undocumented

embedded: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.embedded

Undocumented

html_scaled_image_link: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.html_scaled_image_link

Undocumented

search: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.search

Undocumented

supported_image_types: list[str] = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.supported_image_types

Undocumented

supported_remote_images: bool = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.supported_remote_images
overridden in sphinx.builders.epub3.Epub3Builder

Undocumented

template_dir: str = (source)
overridden in sphinx.builders.epub3.Epub3Builder

Undocumented

files: list[str] = (source)

Undocumented

id_cache: dict[str, str] = (source)

Undocumented

ignored_files = (source)

Undocumented

link_suffix: str = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.link_suffix

Undocumented

out_suffix: str = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.out_suffix

Undocumented

playorder: int = (source)

Undocumented

refnodes = (source)

Undocumented

tocid: int = (source)

Undocumented

use_index = (source)
overrides sphinx.builders.html.StandaloneHTMLBuilder.use_index

Undocumented