{"id":19388851,"url":"https://github.com/linkml/linkml-project-cookiecutter","last_synced_at":"2025-05-07T10:12:44.110Z","repository":{"id":65815344,"uuid":"533393085","full_name":"linkml/linkml-project-cookiecutter","owner":"linkml","description":"A cookiecutter for linkml projects. An equivalent of `linkml-ws new project-name`.","archived":false,"fork":false,"pushed_at":"2024-10-25T15:02:38.000Z","size":212,"stargazers_count":19,"open_issues_count":28,"forks_count":18,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-12-14T01:11:30.878Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linkml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-06T15:42:53.000Z","updated_at":"2024-12-09T03:36:06.000Z","dependencies_parsed_at":"2023-12-01T23:29:19.656Z","dependency_job_id":"75d47999-4922-4317-aab8-cb1e9ba8ac2d","html_url":"https://github.com/linkml/linkml-project-cookiecutter","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkml%2Flinkml-project-cookiecutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkml%2Flinkml-project-cookiecutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkml%2Flinkml-project-cookiecutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkml%2Flinkml-project-cookiecutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkml","download_url":"https://codeload.github.com/linkml/linkml-project-cookiecutter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231439068,"owners_count":18376836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T10:13:52.827Z","updated_at":"2025-05-07T10:12:44.097Z","avatar_url":"https://github.com/linkml.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LinkML Project Cookiecutter\n\nA [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template for projects using [LinkML](https://github.com/linkml/linkml).\n\n## Prerequisites\n\nThe following are required and recommended tools for using this cookiecutter and the LinkML project that it generates. This is all one-time setup, so if you have already done it skip to the [next section](#creating-a-new-project)!\n\n  * **Python \u003e= 3.9**\n\n    LinkML tools are mainly written in Python, so you will need a recent Python interpreter to run this generator and to use the generated project.\n\n  * **pipx**\n\n    pipx is a tool for managing isolated Python-based applications. It is the recommended way to install Poetry and cruft. To install pipx follow the instructions here: https://pypa.github.io/pipx/installation/\n\n  * **Poetry**\n\n    Poetry is a Python project management tool. You will use it in your generated project to manage dependencies and build distribution files. The template requires poetry version 2.0 or newer. If you have pipx installed ([alternative installation methods](https://python-poetry.org/docs/#installation) are available) you can install Poetry by running:\n\n     ```shell\n     pipx install poetry\n     ```\n\n    - For having both Poetry 2.x and Poetry 1.x installed at the same time,\n      pipx has the option to install another version with a suffix-modified name,\n      here \"poetry1\",\n\n      ```bash\n        `pipx install --suffix=1 \"poetry\u003c2.0\"`.\n      ```\n\n    This project manages project-level configuration. User-level [configuration](https://python-poetry.org/docs/configuration/), if needed, is your responsibility.\n\n  * **Poetry private repository**\n\n    Sandboxed environments have private pypi repositories. Poetry supports project-level [repository](https://python-poetry.org/docs/repositories/), but it is recommended to configure [this plugin](https://pypi.org/project/poetry-plugin-pypi-mirror) to persist repository across all poetry projects (and avoid cookiecutter failure):\n    ```shell\n    pip3 install poetry-plugin-pypi-mirror --user\n    # example, add line to `~/.profile` for persistence\n    export POETRY_PYPI_MIRROR_URL = \"https://pypi-proxy.myorg.com/repository/pypi-all/simple\"\n    ```\n\n  * **Poetry Dynamic Versioning Plugin**:\n\n    This plugin automatically updates certain version strings in your generated project when you publish it. Your generated project will automatically be set up to use it. Install it by running:\n    ```shell\n    poetry self add \"poetry-dynamic-versioning[plugin]\"\n    ```\n\n\n  * **cruft**\n\n    cruft is a tool for generating projects based on a cookiecutter (like this one!) as well as keeping those projects updated if the original cookiecutter changes. Install it with pipx by running:\n    ```shell\n    pipx install cruft\n    ```\n    You may also choose to not have a persistent installation of cruft, in which case you would replace any calls to the `cruft` command below with `pipx run cruft`.\n\n\n  * **make or just as command runner**\n\n    The project contains a makefile but also a `justfile` with pre-defined complex commands. To execute these commands you either need `make` or [just](https://github.com/casey/just) as an alternative command runner. Especially for Windows users we suggest `just`. Install it by running:\n    ```shell\n    pipx install rust-just\n    ```\n\n## Creating a new project\n\n### Step 1: Generate the project files\n\nTo generate a new LinkML project run the following:\n```bash\ncruft create https://github.com/linkml/linkml-project-cookiecutter\n```\nAlternatively, to add linkml project files to pre-existing directory,\n(perhaps an existing non-linkml project), pass `-f` option:\n```bash\ncruft create -f https://github.com/linkml/linkml-project-cookiecutter\n```\n\nYou will be prompted for a few values.  The defaults are fine for most\nprojects, but do name your project something that makes sense to you!\nThe interactive session will guide you through the process:\n\n1. `project_name`: Name of the project, use kebab-case with no spaces.\nSuggestions:\n    - `patient-observation-schema`\n    - `sample-collection-metadata`\n    - `resume-standard`\n2. `github_org`: Your github username or organization name. This is used to construct links to documentation pages.\n3. `project_description`: Description of the project.\n    - A single brief sentence is recommended\n    - Can easily be modified later\n4. `full_name`: Your name\n5. `email`: Your email\n6. `license`: Choose a license for the project. If your desired license is not listed you can update or remove the `LICNSE` file in the generated project.\n7. `main_schema_class`:\n    - This is used to generate an example schema which you can edit\n    - The value of this field is ignored if this is a schemasheets project\n    - You can always change this later\n    - Examples: `Person`, `Observation`, `Sample`, `Entry`, `Gene`, `Event`\n8. `create_python_project`\n    - If \"Yes\", set this up as a python project\n    - Select Yes if you want to make data classes that can be used by developers\n9. `use_schemasheets`\n    - If \"Yes\", set this to obtain your schema from\n    [schemasheets](https://linkml.io/schemasheets)\n10. `google_sheet_id`\n     - Ignore/use default value if answer to previous question was \"No\"\n     - If you are using schemasheets then enter your google doc ID here\n     - If you like you can leave the default value, and this will use the demo schema\n11. `google_sheet_tabs`\n    - Ignore/use default value if not using schemasheets\n    - If you are using schemasheets, enter a space-separated list of tabs\n    - your tabs in your sheet MUST NOT have spaces in them\n12. `github_token_for_pypi_deployment`:\n    - The github token name which aligns with your autogenerated PyPI token for making releases.\n    - This helps automated releases to PyPI\n    - This should be ignored if this is not a python project\n    - Even if this is a python project, you can leave blank and fill in later\n\n### Step 2: Set up the LinkML project\n\nChange to the folder your generated project is in.\n\nOptionally customize your project if needed:\n\n* pass arguments to linkml generators via 'config.yaml' configuration file;\n* pass supported environment variables via '.env.public' configuration file;\n\nSetup your project\n```bash\ncd my-awesome-schema  # using the folder example above\nmake setup\n```\n\n### Step 3: Edit the schema\n\nEdit the schema (the .yaml file) in the\n`src/my_awesome_schema/schema` folder\n\n```bash\nnano src/my_awesome_schema/schema/my_awesome_schema.yaml\n```\n\n### Step 4: Validate the schema\n\n```bash\nmake test\n```\n\n### Step 5: Generate documentation locally\n\nLinkML generates schema documentation automatically. The template comes with GitHub Actions that generate and publish the documentation when you push schema changes to GitHub. The published documentation can be found at a URL like this one:\n`https://{github-user-or-organization}.github.io/{project-name}/`\n\nYou can also preview the documentation locally before pushing to GitHub by running:\n\n```bash\nmake serve\n```\n\n### Step 6: Create a GitHub project\n\n1. 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 those files for you)\n\n2. Add the remote to your local git repository\n\n   ```bash\n   git remote add origin https://github.com/{github-user-or-organization}/{project-name}.git\n   git branch -M main\n   git push -u origin main\n   ```\n\n3. Configure your repository for deploying the documentation as GitHub pages\n\n* Under Settings \u003e Actions \u003e General in section \"Workflow Permissions\" mark \"Read repository and packages permission\".\n* Under Pages in section \"Build and Deployment\":\n  * Under \"Source\" select \"Deploy from a branch\"\n  * Under \"Branch\" select \"gh-pages\" and \"/ (root)\"\n\n### Step 7: Register the schema\n\nSee [How to register a schema](https://linkml.io/linkml/faq/contributing.html#how-do-i-register-my-schema)\n\n### Making releases\n\nSee [How to Manage Releases of your LinkML Schema](https://linkml.io/linkml/howtos/manage-releases.html)\n\n## Keeping your project up to date\n\nIn order to be up-to-date with the template, first check if there is a mismatch\nbetween the project's boilerplate code and the template by running:\n\n```bash\ncruft check\n```\n\nThis indicates if there is a difference between the current project's\nboilerplate code and the latest version of the project template. If the project\nis up-to-date with the template:\n\n```output\nSUCCESS: Good work! Project's cruft is up to date and as clean as possible :).\n```\n\nOtherwise, it will indicate that the project's boilerplate code is not\nup-to-date by the following:\n\n```output\nFAILURE: Project's cruft is out of date! Run `cruft update` to clean this mess up.\n```\n\nFor viewing the difference, run `cruft diff`. This shows the difference between the project's boilerplate code and the template's latest version.\n\nAfter running `cruft update`, the project's boilerplate code will be updated to the latest version of the template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkml%2Flinkml-project-cookiecutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkml%2Flinkml-project-cookiecutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkml%2Flinkml-project-cookiecutter/lists"}