From 6a8c43eca3ee3f05b924000c8c7a2cf4f10790f7 Mon Sep 17 00:00:00 2001 From: Rising Odegua Date: Mon, 19 Apr 2021 08:36:12 +0100 Subject: [PATCH] [Scripts-Readme]m]: Update Readme for using scripts --- scripts/README.md | 81 ++++++++++++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 29 deletions(-) diff --git a/scripts/README.md b/scripts/README.md index e41847a6..1f6ce3fc 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,19 +1,27 @@ -## Steps to use scripts -### Deploy Single dataset with github actions -The github actions below will automatically build and deploy a single dataset to gh-pages branch. Folow the steps below to achieve this: +# Deploying a single page dataset to Github pages +In the following sections, we show you how to deploy a single page, Frictionless dataset to Github pages. We show you three ways to do this as listed below: +* Deploying datasets automatically by setting up a github actions script. +* Deploying datasets from a local bash script with portal code commits +* Deploying datasets from a local bash script without portal code commits -**Step 1:** In the dataset repository you want to deploy, create a github secret with the name `PORTAL_REPO_NAME` and the value should be the name of the repository. +## Deploying datasets automatically by setting up a github actions script. +The github actions below will automatically build and deploy a single page, Frictionless dataset to `gh-pages` branch. Folow the steps below to achieve this: + +### Step 1 +In the dataset repository you want to deploy, create a github secret with the name `PORTAL_REPO_NAME` and the value should be the name of the repository. See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets) -**Step 2:** Clone/Pull the dataset repository you want deploy: +### Step 2 +Clone/Pull the dataset repository you want deploy: ```bash git clone https://github.com/datasets/finance-vix ``` -**Step 3:** Create a `.github/workflow` directory and add a `main.yml` file with the following content: +### Step 3 + Create a `.github/workflow` directory and add a `main.yml` file with the following content: ```bash name: github pages @@ -46,39 +54,45 @@ jobs: ``` You can see/download the action file [here]("./actions/single-dataset-ssg.yml") -**Step 3:** Commit and push your code: +### Step 3 + Commit and push your code: ```bash git add . git commit -m "Build dataset page" git push ``` -**Step 4:** +### Step 4 Wait for a while as your page builds, and once you see the green check mark, navigate to your repository's github `pages` in settings, set the `source` to `gh-pages` and folder to `/root`: -**Step 5:** +### Step 5 Open your deployed site at `https:///github.io//index.html` - ______ +### Deploy single dataset without commiting portaljs code +Users who want to deploy datasets from a local bash script +without saving/commiting the portal.js code, can use the script shown below. -## Other build options -### Deploy single dataset with no portal commit -This script creates and commit only the build files from nextjs to the gh-pages branch. +Using this script means you do not have access to the portal.js code used to generate the dataset page, and as such cannot modify/extend it. -**Step 1:** Clone/Pull the dataset repository you want deploy. For example: +This script creates and commit only the build/output files to the gh-pages branch. Follow the steps below to achieve this. + +### Step 1 + Clone/Pull the dataset repository you want deploy. For example: ```bash git clone https://github.com/datasets/finance-vix cd finance-vix ``` -**Step 2:** In a terminal, export an env variable with the name of your dataset github repo. +### Step 2 +In a terminal, export an env variable with the name of your dataset github repo. For example if deploying https://github.com/datasets/finance-vix, then export the name as: ```bash export PORTAL_REPO_NAME=finance-vix ``` -**Step 3:** In the dataset repository's root folder, create a file called `portal.sh` and paste the following content: +### Step 3 + In the dataset repository's root folder, create a file called `portal.sh` and paste the following content: ```bash #!/bin/bash git checkout -b gh-pages @@ -108,45 +122,53 @@ git add $PWD'/_next' $PWD'/index.html' $PWD'/dataset' $PWD'/404.html' $PWD'/.noj git commit -m "Build new dataset page" git push origin gh-pages ``` -**Step 4:** Run the bash script in a terminal with: +### Step 4 + Run the bash script in a terminal with: ```bash source portal.sh ``` > Note: Use `source` instead of `bash` so that the script can work well with environment variables. -**Step 5:** +### Step 5 Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root: -**Step 5:** +### Step 6 Open your deployed site at `https:///github.io/` ____ -### Deploy single dataset with portal commit -This script creates and commit the portal code and also adds an automated script to deploy to gh-page. Follow the steps below to use this script. +## Deploy single dataset with portal commit +Users who want access to the portal.js code used for generating the dataset page can use the script shown in the following section. -**Step 1:** Create a Github Personal Access Token (PAT). See steps [here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +This script creates and commit the portal.js code to the root branch and also adds an automated script to deploy to gh-page. Follow the steps below to use this script. -**Step 2:** In the dataset repository you want to deploy, create a github secret with the name `PORTAL_NEXT_TOKEN`. The value should be the PAT created in step 1. See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets) +### Step 1 + Create a Github Personal Access Token (PAT). See steps [here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) + +### Step 2 + In the dataset repository you want to deploy, create a github secret with the name `PORTAL_NEXT_TOKEN`. The value should be the PAT created in step 1. See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets) > Note: Without the PAT and the secret configured, the automatic build will fail. -**Step 3:** Clone/Pull the dataset repository you want deploy. For example: +### Step 3 + Clone/Pull the dataset repository you want deploy. For example: ```bash git clone https://github.com/datasets/finance-vix cd finance-vix ``` -**Step 4:** In your computer's terminal/command prompt, export an environment variable with the name of your dataset's github repo. +### Step 4 + In your computer's terminal/command prompt, export an environment variable with the name of your dataset's github repo. For example if you want to deploy the dataset at https://github.com/datasets/finance-vix, then export the name using the command: ```bash export PORTAL_REPO_NAME=finance-vix ``` -**Step 5:** Create a file called `portal.sh` and paste the following content: +### Step 5 + Create a file called `portal.sh` and paste the following content: ```bash #!/bin/bash rm -rf portal @@ -175,17 +197,18 @@ git commit -m "Add dataset build feature" git push ``` -**Step 6:** Run the bash script with: +### Step 6 + Run the bash script with: ```bash source portal.sh ``` > Note: Use `source` instead of `bash` so that the script can work well with environment variables. -**Step 7:** +### Step 7 Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root: -**Step 8:** +### Step 8 Open your deployed site at `https:///github.io/` ____ \ No newline at end of file