You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template for
4
-
projects using [LinkML](https://github.com/linkml/linkml).
3
+
A [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template for projects using [LinkML](https://github.com/linkml/linkml).
5
4
6
-
## Standard Protocol
5
+
## Prerequisites
7
6
8
-
### Step 1: Create a virtual environment
7
+
The 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]()!
9
8
10
-
Create a Python virtual environment.
11
-
You can read [this guide](https://realpython.com/python-virtual-environments-a-primer/)
12
-
to learn more about them and how to create one. We suggest using poetry, but
13
-
you can use any tool you like. Please note, most LinkML tools work best in
14
-
Python 3.8 or higher.
9
+
***Python >= 3.8**
10
+
11
+
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.
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/
21
17
22
-
```bash
23
-
mkdir linkml-projects
24
-
cd linkml-projects
25
-
poetry init # creates a new poetry project with pyproject.toml
26
-
# Note this is not a new linkml project,
27
-
# it is just a virtual environment to install cruft.
28
-
poetry add click==8.1.3 # this creates your virtual environment.
29
-
```
30
18
31
-
Add `poetry-dynamic-versioning` as a plugin
19
+
***Poetry**
20
+
21
+
Poetry is a Python project management tool. You will use it in your generated project to manage dependencies and build distribution files. If you have pipx installed you can install Poetry by running:
22
+
```shell
23
+
pipx install poetry
24
+
```
25
+
For other installation methods see: https://python-poetry.org/docs/#installation
### Step 2: Install the cruft tool in your virtual environment
30
+
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:
This tool will help you keep your project up to date with the latest LinkML
40
-
tools and best practices.
41
35
42
-
In your poetry virtual environment:
36
+
***cruft**
43
37
44
-
```bash
45
-
poetry shell
46
-
poetry add cruft
47
-
```
38
+
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:
39
+
```shell
40
+
pipx install cruft
41
+
```
42
+
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`.
43
+
44
+
## Creating a new project
48
45
49
-
### Step 3: Use cruft to create your brand new LinkML project
46
+
### Step 1: Generate the project files
50
47
51
-
In your poetry virtual environment:
48
+
To generate a new LinkML project run the following:
@@ -58,115 +55,95 @@ You will be prompted for a few values. The defaults are fine for most
58
55
projects, but do name your project something that makes sense to you!
59
56
The interactive session will guide you through the process:
60
57
61
-
-`project_name`: Name of the project, use kebab-case with no spaces.
62
-
Suggestions:
63
-
-`patient-observation-schema`
64
-
-`sample-collection-metadata`
65
-
-`resume-standard`
66
-
-`project_description`: Description of the project.
67
-
- A single brief sentence is recommended
68
-
- Can easily be modified later
69
-
-`full_name`: Your name
70
-
-`email`: your email
71
-
-`main_schema_class`:
72
-
- This is used to generate an example schema which you can edit
73
-
- The value of this field is ignored if this is a schemasheets project
74
-
- You can always change this later
58
+
1. `project_name`: Name of the project, use kebab-case with no spaces.
59
+
Suggestions:
60
+
- `patient-observation-schema`
61
+
- `sample-collection-metadata`
62
+
- `resume-standard`
63
+
2. `github_org`: Your github username or organization name. This is used to construct links to documentation pages.
64
+
3. `project_description`: Description of the project.
65
+
- A single brief sentence is recommended
66
+
- Can easily be modified later
67
+
4. `full_name`: Your name
68
+
5. `email`: Your email
69
+
6. `license`: Choose a license forthe project. If your desired license is not listed you can update or remove the `LICNSE` filein the generated project.
70
+
7. `main_schema_class`:
71
+
- This is used to generate an example schema which you can edit
72
+
- The value of this field is ignored if this is a schemasheets project
- Ignore/use default value if answer to previous question was "No"
83
+
- If you are using schemasheets then enter your google doc ID here
84
+
- If you like you can leave the default value, and this will use the demo schema
85
+
11. `google_sheet_tabs`
86
+
- Ignore/use default value if not using schemasheets
87
+
- If you are using schemasheets, enter a space-separated list of tabs
88
+
- your tabs in your sheet MUST NOT have spaces in them
89
+
12. `github_token_for_pypi_deployment`:
90
+
- The github token name which aligns with your autogenerated PyPI token for making releases.
91
+
- This helps automated releases to PyPI
92
+
- This should be ignored if this is not a python project
93
+
- Even if this is a python project, you can leave blank and fill in later
94
+
95
+
### Step 2: Set up the LinkML project
111
96
112
97
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.
113
98
114
99
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.
115
100
116
-
117
101
Change to the folder your generated project is in
118
102
119
103
```bash
120
104
cd my-awesome-schema # using the folder example above
LinkML 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:
You can also preview the documentation locally before pushing to GitHub by running:
146
129
147
130
```bash
148
131
make serve
149
132
```
150
133
151
-
### Step 8: Create a github project
134
+
### Step 6: Create a GitHub project
152
135
153
-
1. Go to [https://github.com/new] and follow the instructions, being sure to
154
-
NOT add a README or .gitignore file (this cookiecutter template will take
155
-
care of this for you)
136
+
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 those files for you)
0 commit comments