Docs#

linkml.generators.docgen.DIALECT#

alias of MarkdownDialect

class linkml.generators.docgen.DiagramType(value)[source]#

An enumeration.

er_diagram = 'er_diagram'#
mermaid_class_diagram = 'mermaid_class_diagram'#
plantuml_class_diagram = 'plantuml_class_diagram'#
class linkml.generators.docgen.DocGenerator(schema: str | ~typing.TextIO | ~linkml_runtime.linkml_model.meta.SchemaDefinition | ~linkml.utils.generator.Generator | ~pathlib.Path, schemaview: ~linkml_runtime.utils.schemaview.SchemaView | None = None, format: str | None = None, metadata: bool = True, useuris: bool | None = None, log_level: int | None = 30, mergeimports: bool | None = True, source_file_date: str | None = None, source_file_size: int | None = None, logger: ~logging.Logger | None = None, verbose: bool | None = None, output: str | None = None, namespaces: ~linkml_runtime.utils.namespaces.Namespaces | None = None, directory_output: bool = False, base_dir: str | None = None, metamodel_name_map: ~typing.Dict[str, str] | None = None, importmap: str | ~typing.Mapping[str, str] | None = None, emit_prefixes: ~typing.Set[str] = <factory>, metamodel: ~linkml.utils.schemaloader.SchemaLoader | None = None, stacktrace: bool = False, dialect: ~linkml.generators.docgen.MarkdownDialect | str | None = None, sort_by: str = 'name', template_mappings: ~typing.Dict[str, str] | None = None, directory: str | None = None, index_name: str = 'index', template_directory: str | None = None, diagram_type: ~linkml.generators.docgen.DiagramType | str | None = None, include_top_level_diagram: bool = False, example_directory: str | None = None, example_runner: ~linkml.workspaces.example_runner.ExampleRunner = <factory>, genmeta: bool = False, gen_classvars: bool = True, gen_slots: bool = True, no_types_dir: bool = False, use_slot_uris: bool = False, use_class_uris: bool = False, hierarchical_class_view: bool = False, **_kwargs)[source]#

Generates documentation from a schema

Note: this is a replacement for MarkdownGenerator

Documents can be generated using either provided Jinja2 templates, or by providing your own

Currently the provided templates are for markdown but this framework allows direct generation to rst, html, etc

This works via jinja2 templates (found in docgen/ folder). By default, only markdown templates are provided. You can either override these, or you can create entirely different templates e.g. for html, latex, etc

The template folder is expected to have files:

  • class.FMT.jinja2

  • enum.FMT.jinja2

  • type.FMT.jinja2

  • slot.FMT.jinja2

  • schema.FMT.jinja2

  • subset.FMT.jinja2

  • index.FMT.jinja2

Most of these accept a jinja2 variable element, except index, schema, which accept schema. See docgen for examples This will generate a single document for every

  • class, enum, type, slot

  • subset

  • imported schema

It will also create an index file

all_class_objects() → Iterator[ClassDefinition][source]#

all class objects in schema

Ensures rank is non-null :return: iterator

all_enum_objects() → Iterator[EnumDefinition][source]#

all enum objects in schema

Ensures rank is non-null :return: iterator

all_slot_objects() → Iterator[SlotDefinition][source]#

all slot objects in schema

Ensures rank is non-null :return: iterator

all_subset_objects() → Iterator[SubsetDefinition][source]#

all enum objects in schema

Ensures rank is non-null :return: iterator

all_type_object_names() → List[TypeDefinitionName][source]#
all_type_objects() → Iterator[TypeDefinition][source]#

all type objects in schema

Ensures rank is non-null :return: iterator

static bullet(e: Element, meta_slot: SlotDefinitionName, backquote=False) → str[source]#

Render tag-value for an element as a bullet

Limitations: currently hardcoded to be markdown :param e: element that holds the property, e.g. Person :param meta_slot: metamodel property to be shown, e.g. comments :param backquote: if true, render as backquote :return: formatted string

static cardinality(slot: SlotDefinition) → str[source]#

Render combination of required, multivalued, and recommended as a range, e.g. 0..* :param slot: :return:

class_hierarchy_as_tuples() → Iterator[Tuple[int, ClassDefinitionName]][source]#

Generate a hierarchical representation of all classes in the schema

This is represented as a list of tuples (depth: int, cls: ClassDefinitionName), where the order is pre-order depth first traversal

This can then be used to draw a hierarchy within jinja in a number of ways; e.g

  • markdown (by using indentation of “ “ * depth on a list)

  • tables (by placing fake indentation e.g using underscores)

Simply iterate through all tuples, drawing each in the appropriate way

Note: By default all classes are ordered alphabetically

Returns:

tuples (depth: int, cls: ClassDefinitionName)

class_induced_slots(class_name: ClassDefinitionName) → Iterator[SlotDefinition][source]#

Yields all induced slots for a class

Ensures rank is non-null

Parameters:

class_name –

Returns:

iterator

diagram_type: DiagramType | str | None = None#

style of diagram (ER, UML)

dialect: MarkdownDialect | str | None = None#

markdown dialect (e.g MyST, Python)

directory: str = None#

directory in which to write documents

example_directory: str | None = None#
example_object_blobs(class_name: str) → List[Tuple[str, str]][source]#

Fetch list of all examples of a class.

Parameters:

class_name – class for which we want to determine the examples

Returns:

list of all examples of a class

example_runner: ExampleRunner#
gen_classvars: bool = True#
gen_slots: bool = True#
generatorname: ClassVar[str] = 'docgen.py'#

Name of the generator. Override with os.path.basename(__file__)

generatorversion: ClassVar[str] = '0.0.1'#

Version of the generator. Consider deprecating and instead use overall linkml version

genmeta: bool = False#
static get_direct_slot_names(cls: ClassDefinition) → List[SlotDefinitionName][source]#

Fetch list of all own attributes of a class, i.e., all slot names of slots that belong to the domain of a class.

Parameters:

cls – class for which we want to determine the attributes

Returns:

list of names of all own attributes of a class

get_direct_slots(cls: ClassDefinition) → List[SlotDefinition][source]#

Fetch list of all own attributes of a class, i.e., all slots that belong to the domain of a class.

Parameters:

cls – class for which we want to determine the attributes

Returns:

list of all own attributes of a class

get_indirect_slots(cls: ClassDefinition) → List[SlotDefinition][source]#

Fetch list of all inherited attributes of a class, i.e., all slots that belong to the domain of a class.

Parameters:

cls – class for which we want to determine the attributes

Returns:

list of all own attributes of a class

get_mixin_inherited_slots(cls: ClassDefinition) → Dict[str, List[str]][source]#

Fetch list of all slots acquired through mixing.

Parameters:

cls – class for which we want to determine the mixed in slots

Returns:

list of all mixed in slots from each mixin class

get_slot_inherited_from(class_name: ClassDefinitionName, slot_name: SlotDefinitionName) → List[ClassDefinitionName][source]#

Get the name of the class that a given slot is inherited from.

Parameters:

  • class_name – name of the class whose slot we are checking

  • slot_name – name of slot in consideration

Returns:

list of classes

hierarchical_class_view: bool = False#
include_top_level_diagram: bool = False#

Whether the index page should include a schema diagram

index_name: str = 'index'#

name of the index document

inheritance_tree(element: Definition, children: bool = True, **kwargs) → str[source]#

Show an element in the context of its is-a hierarchy

Limitations: currently only implemented for markdown (uses nested bullets)

Parameters:

  • element – slot or class to be shown

  • children – if true, show direct children

  • mixins – if true, show mixins alongside each element

  • kwargs –

Returns:

inject_slot_info(slot: SlotDefinition) → SlotDefinition[source]#

Injects additional information into a slot

TODO: move this functionality into schemaview :param slot: :return:

static latex(text: str | None) → str[source]#

Makes text safe for latex

NOTE: may be incomplete!

Parameters:

text –

Returns:

Render an element as a hyperlink

Parameters:

e –

Returns:

Render list of element documentation pages as hyperlinks.

Parameters:

e_list – list of elements

Returns:

list of hyperlinked elements

mermaid_diagram(class_names: List[str | ClassDefinitionName] | None = None) → str[source]#

Render a mermaid diagram for a set of classes

Parameters:

class_names –

Returns:

mermaid_directive() → str[source]#

Writes a mermaid directive. See <https://mermaid-js.github.io/mermaid/#/>_

This comes after the triple-backtick.

Note that the directive varies depending on whether the dialect is the default python markdown (used by mkdocs) or MyST (used if you have a sphinx site)

name(element: Element) → str[source]#

Returns the name of the element in its canonical form

Parameters:

element – SchemaView element definition

Returns:

slot name or numeric portion of CURIE prefixed slot_uri

no_types_dir: bool = False#
static number_value_range(e: SlotDefinition | TypeDefinition) → str[source]#

Render the minimum and maximum values for a slot or type as a range, e.g 5-100

Parameters:

e –

Returns:

requires_metamodel: ClassVar[bool] = False#

Generator queries an instance of the metamodel

schema_title() → str[source]#

Returns the title of the schema.

Uses title field if present, otherwise name

Returns:

serialize(directory: str | None = None) → None[source]#

Serialize a schema as a collection of documents

Parameters:

directory – relative or absolute path to directory in which documents are to be written

Returns:

sort_by: str = 'name'#
template_directory: str = None#

directory for custom templates

template_mappings: Dict[str, str] = None#
uri(element: Element, expand=True) → str[source]#

Fetches the URI string for the relevant element

Parameters:

element –

Returns:

Returns a link string (default: markdown links) for a schema element

Parameters:

element – uri string or linkml model element

Returns:

hyperlinked markdown or web links

use_class_uris: bool = False#
use_slot_uris: bool = False#
uses_schemaloader: ClassVar[bool] = False#

Old-style generator that uses the SchemaLoader and visitor pattern

valid_formats: ClassVar[List[str]] = ['markdown', 'rst', 'html', 'latex']#

Allowed formats - first format is default

visit_all_class_slots: ClassVar[bool] = False#

False means only visit own slots, True means visit all slots

Type:

Visitor ClassVar

yaml(element: Element, inferred=False) → str[source]#

Render element as YAML

Parameters:

  • element –

  • inferred – (classes only) show all induced slots as attributes

Returns:

yaml string

class linkml.generators.docgen.MarkdownDialect(value)[source]#

An enumeration.

myst = 'myst'#
python = 'python'#
linkml.generators.docgen.customize_environment(env: Environment)[source]#
linkml.generators.docgen.enshorten(input)[source]#

Custom filter to truncate any long text intended to go in a table, and to remove anything after a newline