Document

Classes and functions for rendering documents.

class disseminate.document.document.Document(src_filepath, environment, parent_context=None, level=1)

Bases: object

A base class document rendered from a source file to one or more target files.

Parameters
src_filepathUnion[SourcePath, str]

The path (an absolute path or a path relative to the current directory) for the document (markup source) file of this document.

target_rootOptional[Union[TargetPath, str]]

The path for the rendered target files. Subdirectories for the targets will be created. (ex: ‘html’ ‘tex’) By default, if not specified, the target_root will be one directory above the project_root.

parent_contextOptional[DocumentContext]

The context of the parent document or default context.

levelOptional[int]

The level of document loaded. Sub-documents are loaded at a higher level (>1) than the root document.

Attributes
src_filepathSourcePath

The filename and path for this document’s (markup source) file. This file should exist. ex: ‘src/chapter1/chapter1.dm’

contextDocumentContext

A context dict with the values needed to render a target document.

subdocumentsOrderedDict[SourcePath, Document]

An ordered dict with the sub-documents included in this document. The keys are src_filepaths, and the values are the sub-documents themselves. The documents are ordered according to their placement in the document tree (project).

This document owns the sub-documents and only weak references to these documents should be made to these documents. (i.e. when the sub-documents dict is cleared, the memory for the document objects should be released)

build(complete=True)

Run a build of the document and all subdocuments.

build_needed()

Evaluate whether a build is required

property doc_id

The unique string identifier (within a project) for the document.

property doc_ids

The list of all doc_id for this document and all subdocuments.

documents_by_id(document=None, only_subdocuments=False, recursive=True)

Produce an ordered dict of a document and sub-documents entered by doc_id.

Parameters
documentOptional[Document]

The document for which to create the document dict. If None is specified, this document will be used.

only_subdocumentsOptional[bool]

If True, only the sub-documents will be returned (not this document or the document specified.)

recursiveOptional[bool]

If True, the sub-documents of sub-documents are returned ( in order) in the ordered dict as well

Returns
document_dictOrderedDict[str, Document]

An ordered dict of documents. The keys are doc_ids and the values are document objects.

documents_dict(document=None, only_subdocuments=False, recursive=False)

Produce an ordered dict of a document and all its sub-documents.

Parameters
documentOptional[Document]

The document for which to create the document list. If None is specified, this document will be used.

only_subdocumentsOptional[bool]

If True, only the sub-documents will be returned (not this document or the document specified.)

recursiveOptional[bool]

If True, the sub-documents of sub-documents are returned (in order) in the ordered dict as well

Returns
document_dictOrderedDict[SourcePath, Document]

An ordered dict of documents. The keys are src_filepaths and the values are document objects.

documents_list(document=None, only_subdocuments=False, recursive=False)

Produce an ordered list of a document and all its sub-documents.

Parameters
documentOptional[Document]

The document for which to create the document list.

only_subdocumentsOptional[bool]

If True, only the sub-documents will be returned (not this root document or the document specified.

recursiveOptional[bool]

If True, the sub-documents of sub-documents are returned (in order) in the list as well

Returns
document_listList[Document]

An ordered list of documents.

load(reload=False, level=1)

Load or reload the document into the context.

Parameters
reloadOptional[bool]

If True, force the reload of the document.

levelOptional[int]

The level of document loaded. Sub-documents are loaded at a higher level (>1) than the root document.

Returns
document_loadedbool

True, if a sub-document was (re)loaded.

load_required()

Evaluate whether a load is required.

Returns
load_requiredbool

True, if a load is required. False if a load isn’t required.

load_subdocuments(level=1)

Load the sub-documents listed in the include entries in the context.

Parameters
levelOptional[int]

The level of document loaded. Sub-documents are loaded at a higher level (>1) than the root document.

Returns
document_loadedbool

True, if a sub-document was (re)loaded.

property short

The short title for the document.

target_filepath(target)

The filepath for the given target extension.

Parameters
targetstr

The target extension for the target file. ex: ‘.html’ or ‘.tex’

Returns
target_filepathUnion[TargetPath, None]

The target filepath.

property targets

The targets dict.

There may be more targets in this dict than those listed in the context because some targets may be intermediary targets in a cache path.

Returns
targetsDict[str, TargetPath]

The targets are a dict with the target extension as keys (ex: ‘.html’) and the value is the target_filepath for that target. (ex: ‘html/index.html’) These paths are target paths.

property title

The title for the document.