LinkML Project Cookiecutter

A Cookiecutter template for projects using LinkML.

Standard Protocol

Step 1: Create a virtual environment

Create a Python virtual environment. You can read this guide to learn more about them and how to create one. We suggest using poetry, but you can use any tool you like. Please note, most LinkML tools work best in Python 3.8 or higher.

An example using poetry:

curl -sSL https://install.python-poetry.org | python3 -

mkdir linkml-projects
cd linkml-projects
poetry init # creates a new poetry project with pyproject.toml
            # Note this is not a new linkml project,
            # it is just a virtual environment to install cruft.
poetry add click==8.1.3  # this creates your virtual environment.

Add poetry-dynamic-versioning as a plugin

poetry self add "poetry-dynamic-versioning[plugin]"

Step 2: Install the cruft tool in your virtual environment

This tool will help you keep your project up to date with the latest LinkML tools and best practices.

In your poetry virtual environment:

poetry shell
poetry add cruft

Step 3: Use cruft to create your brand new LinkML project

In your poetry virtual environment:

cruft create https://github.com/linkml/linkml-project-cookiecutter

You will be prompted for a few values. The defaults are fine for most projects, but do name your project something that makes sense to you! The interactive session will guide you through the process:

• project_name: Name of the project, use kebab-case with no spaces. Suggestions:
  • patient-observation-schema
  • sample-collection-metadata
  • resume-standard
• project_description: Description of the project.
  • A single brief sentence is recommended
  • Can easily be modified later
• full_name: Your name
• email: your email
• main_schema_class:
  • This is used to generate an example schema which you can edit
  • The value of this field is ignored if this is a schemasheets project
  • You can always change this later
    • Examples: Person, Observation, Sample, Entry, Gene, Event
• create_python_project
  • If "Yes", set this up as a python project
  • Select Yes if you want to make data classes that can be used by developers
• use_schemasheets
  • If "Yes", set this to obtain your schema from schemasheets
• google_sheet_id
  • Ignore/use default value if answer to previous question was "No"
  • If you are using schemasheets then enter your google doc ID here
  • If you like you can leave the default value, and this will use the demo schema
• google_sheet_tabs
  • Ignore/use default value if not using schemasheets
  • If you are using schemasheets, enter a space-separated list of tabs
  • your tabs in your sheet MUST NOT have spaces in them
• github_token_for_pypi_deployment:
  • The github token name which aligns with your autogenerated PyPI token for making releases.
  • This helps automated releases to PyPI
  • This should be ignored if this is not a python project
  • Even if this is a python project, you can leave blank and fill in later

This will generate the project folder abiding by the template configuration specified by linkml-project-cookiecutter in the cookiecutter.json file.

This will generate the project folder very similar to what is mentioned in the linkml-project-template project.

For more docs, see linkml/linkml-project-cookiecutter.

Step 4: Setup the LinkML project

Optionally, pass custom configuration to linkml generators by tuning the global configuration file 'config.yaml' with preferred options. An example file is supplied by the project to illustrate interface and defaults.

Additionally, pass command-line arguments to linkml generators inside the Makefile via environment variables in 'config.env' file. An example file is supplied by the project, passing '--config-file config.yaml' to gen-project.

Change to the folder your generated project is in

cd my-awesome-schema  # using the folder example above
make setup

Step 5: Edit the schema

Edit the schema (the .yaml file) in the linkml-projects/my-awesome-schema/src/my_awesome_schema/schema folder

nano src/my_awesome_schema/schema/my_awesome_schema.yaml

Step 6: Validate the schema

make test

Step 7: Auto-generate your documentation locally

LinkML generates schema documentation automatically. Step 7 here, allows you to preview the documentation that LinkML generates before pushing to GitHub. Note, this template comes with GitHub Actions that autogenerate this documentation on release of your schema repository at a URL like this one: [https://my-user-or-organization.github.io/my-awesome-schema/]

make serve

Step 8: Create a github project

1. Go to [https://github.com/new] and follow the instructions, being sure to NOT add a README or .gitignore file (this cookiecutter template will take care of this for you)

2. Add the remote to your local git repository

   git remote add origin https://github.com/my-user-or-organization/my-awesome-schema.git
   git branch -M main
   git push -u origin main

Step 9: Deploy documentation

make deploy

Step 10: Register the schema

See How to register a schema

Keeping your project up to date

In order to be up-to-date with the template, first check if there is a mismatch between the project's boilerplate code and the template by running:

poetry shell
cruft check

This indicates if there is a difference between the current project's boilerplate code and the latest version of the project template. If the project is up-to-date with the template:

SUCCESS: Good work! Project's cruft is up to date and as clean as possible :).

Otherwise, it will indicate that the project's boilerplate code is not up-to-date by the following:

FAILURE: Project's cruft is out of date! Run `cruft update` to clean this mess up.

For viewing the difference, run cruft diff. This shows the difference between the project's boilerplate code and the template's latest version.

After running cruft update, the project's boilerplate code will be updated to the latest version of the template.