Disseminate

Document Processing

Installation

Markup Language

Projects

Interfaces

Development

Ref

The Ref tag to reference captions and other labels.

class disseminate.tags.ref.Ref(name, content, *args, **kwargs)

Bases: disseminate.tags.tag.Tag

A tag to reference a label.

Attributes
doc_idstr

The doc_id for the document that owns the label referenced. This might be different to the doc_id listed in the context if a reference is made to a label in another document.

label_idstr

The id of the label referenced by this tag.

.. note:: The ref tag takes the label id as the content. If the label is

not found, a label manager exception is raised. (label_manager.exceptions.LabelNotFound)

default_fmt(content=None, attributes=None, cache=None, **kwargs)

Convert the tag to a text string.

Parameters
contentOptional[Union[str, List[Union[str, list, Tag]]]

Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.

attributesOptional[Union[str, Attributes]]

Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.

cacheOptional[dict]

If specified, the cache values will be used instead of being evaluated. Possibilities: - ‘label’: types.Label - ‘documents_by_id’: Dict[str, document.Document]

Returns
text_stringstr

A text string with the tags stripped.

document(cache=None)

The document that owns the label referenced by this tag.

Parameters
cacheOptional[dict]

If specified, the cache values will be used instead of being evaluated. Possibilities: - ‘label’: types.Label - ‘documents_by_id’: Dict[str, document.Document]

Returns
documentUnion[Document, None]

The document that owns the label referenced by this tag, if available. None, if a document could not be found.

html_fmt(content=None, attributes=None, cache=None, format_func='html_fmt', method='html', level=1, **kwargs)

Convert the tag to an (x)html string or (x)html element.

Parameters
contentOptional[Union[str, List[Union[str, list, Tag]]]

Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.

attributesOptional[Union[str, Attributes]]

Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.

cacheOptional[dict]

If specified, the cache values will be used instead of being evaluated. Possibilities: - ‘label’: types.Label - ‘documents_by_id’: Dict[str, document.Document] - ‘format_str’: str

format_funcOptional[str]

The tag format function to use in rendering the reference tag. (ex: ‘html_fmt’ or ‘xhtml_fmt’)

methodOptional[str]

The rendering method for the string. ex: ‘html’ or ‘xml’

levelOptional[int]

The level of the tag.

Returns
htmlstr or html element

A string in HTML format or an HTML element (lxml.builder.E).

property label

Retrieve the label for this ref tag.

tex_fmt(content=None, attributes=None, mathmode=False, cache=None, level=1, **kwargs)

Format the tag in LaTeX format.

Note

This function renders tex links to compiled pdf documents

Parameters
contentOptional[Union[str, List[Union[str, list, Tag]]]

Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.

attributesOptional[Union[str, Attributes]]

Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.

mathmodeOptional[bool]

If True, the tag will be rendered in math mode. Otherwise (default) latex text mode is assumed.

cacheOptional[dict]

If specified, the cache values will be used instead of being evaluated. Possibilities: - ‘label’: types.Label - ‘documents_by_id’: Dict[str, document.Document]

levelOptional[int]

The level of the tag.

Returns
tex_stringstr

The formatted tex string.

url(target='.html', include_anchor=True, cache=None)

The url path for the document referenced by the label for this tag.

Parameters
targetOptional[str]

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

include_anchorOptional[bool]

If True (default), the html link anchor will be appended to the url path.

cacheOptional[dict]

If specified, the cache values will be used instead of being evaluated. Possibilities: - ‘label’: types.Label - ‘documents_by_id’: Dict[str, document.Document]

Returns
url_pathstr

The url path for the document owning the label referenced by this tag.

exception disseminate.tags.ref.RefError

Bases: Exception

A reference to a document could not be found.

Receivers

The Ref tag to reference captions and other labels.

disseminate.tags.ref.add_ref_labels(builder, **kwargs)

Find and add the labels associated with Ref tags for all tags in the context.