Documentation#

Overview#

Being able to automatically generate technical documentation pages for your LinkML schema is an important feature of the LinkML framework. The linkml library is bundled with a generator (invoked using the gen-doc command) which can be used to automatically create individual Markdown pages for each of the elements (classes, slots, enumerations, etc.) in your schema.

The documentation pages are an important resource for consumers of the schema because it provides a user-friendly way for users to explore and understand your schema.

If you use the official LinkML cookicutter to create your schema, it will add a static site generator framework to your environment. There are many static site generator frameworks available, but the one recommended by LinkML is MkDocs. MkDocs can be used to convert Markdown files/pages into HTML pages. The reason we recommend converting to HTML is so that the pages can be deployed to a static site hosting service like GitHub Pages. Again, if you have used the cookicutter to create your schema, you will find a Makefile in your project folder with shortcuts (Makefile targets) to help you build and deploy your documentation easily.

Another important detail about the information contained in the technical documentation pages is the fact that it also has automatically generated Mermaid class diagrams embedded on the class documentation pages. These diagrams summarize the relationships between various classes and slots in your schema.

Optionally linkml also allows you to exercise more granular control on the layout and content rendered on your documentation pages. This customization is facilitated by the modification of the base jinja2 templates that are used to control the layout and content of the documentation pages. There are jinja2 templates for each of the elements in your schema, and you can modify whichever you need to based on your requirements.

../_images/documentation_generation_schematic.png

Figure.: schematic diagram explaining the working mechanism of the ``gen-doc`` module

Command Line#

gen-doc#

Generate documentation folder from a LinkML YAML schema

Currently a default set of templates for markdown is provided (see the folder linkml/generators/docgen/)

If you specify another format (e.g. html) then you need to provide a template_directory argument, with a template for each type of entity inside.

Examples can optionally be integrated into the documentation; to enable this, pass in the –example-directory argument. The example directory should contain one file per example, following the naming convention <ClassName>-<ExampleName>.<extension>.

For example, to include examples on the page for Person, include examples

Person-001.yaml, Person-002.yaml, etc.

Currently examples must be in yaml

gen-doc [OPTIONS] YAMLFILE

Options

-V, --version#: Show the version and exit.

--truncate-descriptions <truncate_descriptions>#

Whether to truncate long (potentially spanning multiple lines) descriptions of classes, slots, etc., in the docs. Set to true for truncated descriptions, and false to display full descriptions.

Default:: True

--subfolder-type-separation, --no-subfolder-type-separation#: Separate type (class, slot, etc.) outputs in different subfolders for navigation purposes

-d, --include <include>#: Include LinkML Schema outside of imports mechanism. Helpful in including deprecated classes and slots in a separate YAML, and including it when necessary but not by default (e.g. in documentation or for backwards compatibility)

--example-directory <example_directory>#: Folder in which example files are found. These are used to make inline examples

--render-imports, --no-render-imports#

Render also the documentation of elements from imported schemas

Default:: False

--hierarchical-class-view, --no-hierarchical-class-view#: Render class table on index page in a hierarchically indented view

--use-class-uris, --no-use-class-uris#: Use IDs from class_uri instead of names

--use-slot-uris, --no-use-slot-uris#: Use IDs from slot_uri instead of names

--template-directory <template_directory>#: Path to the directory with custom jinja2 templates

--genmeta, --no-genmeta#

Generating metamodel. Only use this for generating meta.py

Default:: False

--sort-by <sort_by>#

Metaslot to use to sort elements by e.g. rank, name, title

Default:: 'name'

--include-top-level-diagram, --no-include-top-level-diagram#

Include ER diagram of the entire schema on index page.

Default:: False

--diagram-type <diagram_type>#

Type of UML diagram to be rendered on class documentation pages.

Options:: mermaid_class_diagram | plantuml_class_diagram | er_diagram

--dialect <dialect>#: Dialect or ‘flavor’ of Markdown used.

--index-name <index_name>#

Name of the index document.

Default:: 'index'

-d, --directory <directory>#: Required Path to the directory where you want the Markdown files to be written to

-f, --format <format>#

Output format

Default:: 'markdown'
Options:: markdown | rst | html | latex

--metadata, --no-metadata#

Include metadata in output

Default:: True

--useuris, --metauris#

Use class and slot URIs over model uris

Default:: True

-im, --importmap <importmap>#: Import mapping file

--log_level <log_level>#

Logging level

Default:: 'WARNING'
Options:: CRITICAL | ERROR | WARNING | INFO | DEBUG

-v, --verbose#: Verbosity. Takes precedence over –log_level.

--mergeimports, --no-mergeimports#: Merge imports into source file (default=mergeimports)

--stacktrace, --no-stacktrace#

Print a stack trace when an error occurs

Default:: False

Arguments

YAMLFILE#: Required argument

Code#

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: dict[str, str] = None, importmap: str | ~collections.abc.Mapping[str, str] | None = None, emit_prefixes: 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: 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, truncate_descriptions: bool = True, 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)[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

serialize(directory: str = 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: