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.
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.
- --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, 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