From b83ee284262219e6f81433efd97c354ab8e17155 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:30:19 -0700 Subject: [PATCH 1/7] fix up doc --- README.md | 90 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 59 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index f9f6cdd..957ffc1 100644 --- a/README.md +++ b/README.md @@ -7,28 +7,45 @@ A [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template for pr ### Step 1: Create a virtual environment -1: Create a Python virtual environment. You can read [this +Create a Python virtual environment. You can read [this guide](https://realpython.com/python-virtual-environments-a-primer/) 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. -After creating a virtual environment, it's as simple as: - -1a: [install poetry](https://python-poetry.org/docs/): - -`curl -sSL https://install.python-poetry.org | python3 -` +An example using poetry: +```bash +curl -sSL https://install.python-poetry.org | python3 - +``` -1b: [install cruft](https://cruft.github.io/cruft/): +```bash +mkdir linkml-projects +cd linkml-projects +poetry init # creates a new poetry project with pyproject.toml. Note this is not a linkml project, it is just a virtual environment to install cruft. +poetry add click==8.0.4 +poetry install # this creates your virtual environment. +``` -`pip3 install cruft` +### 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. +```bash +In your poetry virtual environment: -### Use cruft to generate a new project: +2b: [install cruft](https://cruft.github.io/cruft/): +```bash +poetry add cruft +``` -`cruft create https://github.com/linkml/linkml-project-cookiecutter` +### Step 3: Use cruft to create your brand new LinkML project: -Then follow the instructions on the screen, answering questions as best you can. +In your poetry virtual environment: -This kickstarts an interactive session where you declare the following: +```bash +poetry shell +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` @@ -69,53 +86,63 @@ This will generate the project folder very similar to what is mentioned in the [ See [linkml/linkml-project-cookiecutter](https://github.com/linkml/linkml-project-cookiecutter) for more docs. -### Setup the project +### Step 4: Setup the LinkML project Change to the folder your generated project is in -type: - ```bash +cd linkml-projects/my-awesome-schema # using the folder example above make setup ``` -### Edit the schema +### Step 5: Edit the schema -Edit the schema in the src folder +Edit the schema (the .yaml file) in the linkml-projects/my-awesome-schema/src/my_awesome_schema/schema folder +```bash +nano src/my_awesome_schema/schema/my_awesome_schema.yaml +``` + +### Step 6: Validate the schema + +```bash +make test +``` -### Validate the schema +### Step 7: Test the documentation -`make test` +```bash +make serve +``` -### Test the documentation +The result of the 'make server' command will be a URL that you can use to view the documentation. For example: -`make server` -An look at the URL provided +```bash -### Create a github project +### Step 8: Create a github project Go to https://github.com/new and follow the instructions -### Deploy documentation +### Step 9: Deploy documentation `make deploy` -### Register the schema +### Step 10: Register the schema See [How to register a schema](../faq/contributing) -## Alternative protocols - ## 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: +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: -``` +```bash +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: +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 :). @@ -127,7 +154,8 @@ Otherwise, it will indicate that the project's boilerplate code is not up-to-dat 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. +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. From 0d96896cd24306cac94bc0a682e3e503dc9938d9 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:32:43 -0700 Subject: [PATCH 2/7] fix formatting --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 957ffc1..2bdc854 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,8 @@ poetry install # this creates your virtual environment. ### 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. - -```bash In your poetry virtual environment: -2b: [install cruft](https://cruft.github.io/cruft/): ```bash poetry add cruft ``` From ad8809950501bae8be337c32ab038817d9b4404b Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:45:29 -0700 Subject: [PATCH 3/7] add git commands to doc --- README.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2bdc854..44fd5d2 100644 --- a/README.md +++ b/README.md @@ -105,20 +105,30 @@ nano src/my_awesome_schema/schema/my_awesome_schema.yaml make test ``` -### Step 7: Test the documentation +### Step 7: Auto-generate your documentation locally. +LinkML generates schema documenation 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/ + +```bash ```bash make serve ``` -The result of the 'make server' command will be a URL that you can use to view the documentation. For example: - +### Step 8: Create a github project -```bash +8a: 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) -### Step 8: Create a github project +8b: Add the remote to your local git repository` -Go to https://github.com/new and follow the instructions +```bash +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 From f7a90cba85868e450ee95ecf6509b85cebbbd106 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:48:00 -0700 Subject: [PATCH 4/7] typo fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 44fd5d2..b859c6c 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ curl -sSL https://install.python-poetry.org | python3 - ```bash mkdir linkml-projects cd linkml-projects -poetry init # creates a new poetry project with pyproject.toml. Note this is not a linkml project, it is just a virtual environment to install cruft. +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.0.4 poetry install # this creates your virtual environment. ``` From 7b60d68fefe83f0865ab5faa6525d5aad306d4d7 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:49:23 -0700 Subject: [PATCH 5/7] typo fix --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index b859c6c..523fdf9 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ poetry install # this creates your virtual environment. ### 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: ```bash @@ -111,8 +112,6 @@ that LinkML generates before pushing to GitHub. Note, this template comes with 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/ -```bash - ```bash make serve ``` From 599373b232e8c4f495e114be270d1aaca44cd846 Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 13:59:50 -0700 Subject: [PATCH 6/7] setting schemasheets to No by default --- cookiecutter.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cookiecutter.json b/cookiecutter.json index ab5bc07..27f499d 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -4,16 +4,16 @@ "github_org": "my-org", "__source_path": "src/{{cookiecutter.__project_slug}}/schema/{{cookiecutter.__project_slug}}.yaml", "project_description": "This is the project description.", - "full_name": "Harshad Hegde", - "email": "hhegde@lbl.gov", + "full_name": "My Name", + "email": "my-name@my-org.org", "__author": "{{cookiecutter.full_name}} <{{cookiecutter.email}}>", "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"], "google_analytics_gtag": "G-2SYBSJVZ23", "main_schema_class": "Person", "create_python_classes": ["Yes", "No"], "use_schemasheets": [ - "Yes", - "No (next two questions are ignored)" + "No (next two questions are ignored)", + "Yes" ], "google_sheet_id": "1wVoaiFg47aT9YWNeRfTZ8tYHN8s8PAuDx5i2HUcDpvQ", "google_sheet_tabs": "personinfo enums", From e954151253163fc5a4e76f788a8d140444d14a3b Mon Sep 17 00:00:00 2001 From: Sierra Taylor Moxon Date: Thu, 15 Sep 2022 14:22:06 -0700 Subject: [PATCH 7/7] fix typo --- cookiecutter.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookiecutter.json b/cookiecutter.json index 24201ba..c494e1e 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -12,7 +12,7 @@ "main_schema_class": "Person", "create_python_classes": ["Yes", "No"], "use_schemasheets": [ - "No, + "No", "Yes" ], "google_sheet_id": "1wVoaiFg47aT9YWNeRfTZ8tYHN8s8PAuDx5i2HUcDpvQ",