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, 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 = 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, 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, **_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_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, 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]] [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)
- 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#
- 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
- 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
- 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:
- link(e: Definition | DefinitionName, index_link: bool = False) str [source]#
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] [source]#
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
- 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:
- 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:
- subfolder_type_separation: bool = False#
Whether each type (class, slot, etc.) should be put in separate subfolder for navigation purposes
- uri(element: Element, expand=True) str [source]#
Fetches the URI string for the relevant element
- Parameters:
element –
- Returns:
- uri_link(element: Element | str) str [source]#
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
- 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
- class linkml.generators.docgen.MarkdownDialect(value)[source]#
An enumeration.
- myst = 'myst'#
- python = 'python'#
- linkml.generators.docgen.customize_environment(env: Environment)[source]#