Docs

linkml.generators.docgen.DIALECT

alias of MarkdownDialect

class linkml.generators.docgen.DiagramType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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, metamodel_name_map: ~typing.Dict[str, str] = None, importmap: str | ~typing.Mapping[str, str] | None = None, emit_prefixes: ~typing.Set[str] = <factory>, metamodel: ~linkml.utils.schemaloader.SchemaLoader = None, stacktrace: bool = False, include: str | ~pathlib.Path | ~linkml_runtime.linkml_model.meta.SchemaDefinition | None = None, dialect: ~linkml.generators.docgen.MarkdownDialect | str | None = None, sort_by: str = 'name', template_mappings: ~typing.Dict[str, str] = None, directory: str = None, index_name: str = 'index', template_directory: str = None, diagram_type: ~linkml.generators.docgen.DiagramType | str | None = None, include_top_level_diagram: bool = False, subfolder_type_separation: 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, render_imports: bool = False, **_kwargs)

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]

all class objects in schema

Ensures rank is non-null :return: iterator

all_enum_objects() → Iterator[EnumDefinition]

all enum objects in schema

Ensures rank is non-null :return: iterator

all_slot_objects() → Iterator[SlotDefinition]

all slot objects in schema

Ensures rank is non-null :return: iterator

all_subset_objects() → Iterator[SubsetDefinition]

all enum objects in schema

Ensures rank is non-null :return: iterator

all_type_object_names() → List[TypeDefinitionName]

all_type_objects() → Iterator[TypeDefinition]

all type objects in schema

Ensures rank is non-null :return: iterator

static bullet(e: Element, meta_slot: SlotDefinitionName, backquote=False) → str

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

Render combination of required, multivalued, recommended, and exact_cardinality as a range, according to Mermaid conventions. Considers ‘required’ and ‘multivalued’ to set defaults for ‘minimum_cardinality’ and ‘maximum_cardinality’.

Reference: https://mermaid.js.org/syntax/classDiagram.html#cardinality-multiplicity-on-relations

The different cardinality options are: - 1 Only 1 - 0..1 Zero or One - 1..* One or more - * Many - n n (where n>1) - 0..n zero to n (where n>1) - 1..n one to n (where n>1) :param slot: SlotDefinition :return: cardinality string as used in Mermaid diagrams

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

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]

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]]

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]

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]

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]

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]]

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]

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

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

Injects additional information into a slot

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

static latex(text: str | None) → str

Makes text safe for latex

NOTE: may be incomplete!

Parameters:

text –

Returns:

link(e: Definition | DefinitionName, index_link: bool = False) → str

Render an element as a hyperlink

Parameters:

• e –

• index_link – Whether this is a link for the index page or not

Returns:

links(e_list: List[DefinitionName]) → List[str]

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) → str

Render a mermaid diagram for a set of classes

Parameters:

class_names –

Returns:

mermaid_directive() → str

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

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

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

Parameters:

e –

Returns:

render_imports: bool = False

requires_metamodel: ClassVar[bool] = False

Generator queries an instance of the metamodel

schema_title() → str

Returns the title of the schema.

Uses title field if present, otherwise name

Returns:

serialize(directory: str = None) → None

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'

subfolder_type_separation: bool = False

Whether each type (class, slot, etc.) should be put in separate subfolder for navigation purposes

template_directory: str = None

directory for custom templates

template_mappings: Dict[str, str] = None

uri(element: Element, expand=True) → str

Fetches the URI string for the relevant element

Parameters:

element –

Returns:

uri_link(element: Element | str) → str

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

Render element as YAML

Parameters:

• element –

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

Returns:

yaml string

class linkml.generators.docgen.MarkdownDialect(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

myst = 'myst'

python = 'python'

linkml.generators.docgen.customize_environment(env: Environment)

linkml.generators.docgen.enshorten(input)

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