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.
- src_filepathUnion[
- Attributes
- src_filepath
SourcePath
The filename and path for this document’s (markup source) file. This file should exist. ex: ‘src/chapter1/chapter1.dm’
- context
DocumentContext
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)
- src_filepath
- 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
- documentOptional[
- Returns
- document_dictOrderedDict[str,
Document
] An ordered dict of documents. The keys are doc_ids and the values are document objects.
- document_dictOrderedDict[str,
- 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
- documentOptional[
- Returns
- document_dictOrderedDict[
SourcePath
,Document
] An ordered dict of documents. The keys are src_filepaths and the values are document objects.
- document_dictOrderedDict[
- 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
- documentOptional[
- Returns
- document_listList[
Document
] An ordered list of documents.
- document_listList[
- 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.
- target_filepathUnion[
- 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.
- targetsDict[str,
- property title¶
The title for the document.