From 2fb2aefa23181d3912dc4bf99082c9613351c212 Mon Sep 17 00:00:00 2001 From: Luccas Mateus de Medeiros Gomes Date: Mon, 24 Apr 2023 13:20:31 -0300 Subject: [PATCH] [monorepo][sm] - update docs --- site/content/docs/example-ckan.md | 42 ++++++++++--- site/content/docs/example-data-catalog.md | 72 ++++++++++++++++++++--- 2 files changed, 98 insertions(+), 16 deletions(-) diff --git a/site/content/docs/example-ckan.md b/site/content/docs/example-ckan.md index d58f055a..c1f1ae89 100644 --- a/site/content/docs/example-ckan.md +++ b/site/content/docs/example-ckan.md @@ -8,19 +8,47 @@ date: 2023-04-20 This is a repo intended to serve as an example of a data catalog that get its data from a CKAN Instance. -- Creating a new file inside o `examples` with `create-next-app` like so: ``` -npx create-next-app --example https://github.com/datopian/portaljs/tree/main/ --example-path examples/ckan-example +npx create-next-app --example https://github.com/datopian/portaljs/tree/main/examples/ckan-example +cd ``` -- Inside `` go to the `project.json` file and replace all instances of `ckan-example` with `` -- Set the `DMS` env variable to the Url of the CKAN Instance Ex: `export DMS=https://demo.dev.datopian.com` + +- This project uses CKAN as a backend, so you need to point the project to the CKAN Url desired, you can do so by setting up the `DMS` env variable in your terminal or adding a `.env` file with the following content: + +``` +DMS= +``` + - Run the app using: + ``` -nx serve +npm run dev ``` + Congratulations, you now have something similar to this running on `http://localhost:4200` ![](https://media.discordapp.net/attachments/1069718983604977754/1098252297726865408/image.png?width=853&height=461) - If yo go to any one of those pages by clicking on `More info` you will see something similar to this - ![](https://media.discordapp.net/attachments/1069718983604977754/1098252298074988595/image.png?width=853&height=461) + +## Deployment + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fckan-example&env=DMS&envDescription=URL%20For%20the%20CKAN%20Backend%20Ex%3A%20https%3A%2F%2Fdemo.dev.datopian.com) + +By clicking on this button, you will be redirected to a page which will allow you to clone the content into your own github/gitlab/bitbucket account and automatically deploy everything. + + + +## Extra commands + +You can also build the project for production with + +``` +npm run build +``` + +And run using the production build like so: + +``` +npm run start +``` + diff --git a/site/content/docs/example-data-catalog.md b/site/content/docs/example-data-catalog.md index c367a17b..3749170e 100644 --- a/site/content/docs/example-data-catalog.md +++ b/site/content/docs/example-data-catalog.md @@ -6,22 +6,76 @@ date: 2023-04-20 **See the repo:** https://github.com/datopian/portaljs/tree/main/examples/simple-example -This is a repo intended to serve as a simple example of a data catalog that get its data from a series of github repos, you can init an example just like this one by. +- Creating a new project with `create-next-app` like so: -- Creating a new file inside of `examples` with `create-next-app` like so: ``` -npx create-next-app --example https://github.com/datopian/portaljs/tree/main/ --example-path examples/simple-example +npx create-next-app --example https://github.com/datopian/portaljs/tree/main/examples/simple-example +cd ``` -- Inside `` go to the `project.json` file and replace all instances of `simple-example` with `` + +- This project uses the github api, which for anonymous users will cap at 50 requests per hour, so you might want to get a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and add it to a `.env` file inside the folder like so + +``` +GITHUB_PAT= +``` + - Edit the file `datasets.json` to your liking, some examples can be found inside this [repo](https://github.com/datasets) - Run the app using: + ``` -nx serve +npm run dev ``` -Congratulations, you now have something similar to this running on `http://localhost:4200` -![](https://i.imgur.com/JrDLycF.png) - +Congratulations, you now have something similar to this running on `http://localhost:3000` +![](https://i.imgur.com/jAljJ9C.png) If yo go to any one of those pages by clicking on `More info` you will see something similar to this +![](https://i.imgur.com/AoJd4O0.png) + +## Deployment + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fsimple-example) + +By clicking on this button, you will be redirected to a page which will allow you to clone the content into your own github/gitlab/bitbucket account and automatically deploy everything. + + +## Structure of `datasets.json` + +The `datasets.json` file is simply a list of datasets, below you can see a minimal example of a dataset + +```json +{ + "owner": "fivethirtyeight", + "repo": "data", + "branch": "master", + "files": ["nba-raptor/historical_RAPTOR_by_player.csv", "nba-raptor/historical_RAPTOR_by_team.csv"], + "readme": "nba-raptor/README.md" +} +``` + +It has + +- A `owner` which is going to be the github repo owner +- A `repo` which is going to be the github repo name +- A `branch` which is going to be the branch to which we need to get the files and the readme +- A list of `files` which is going to be a list of paths with files that you want to show to the world +- A `readme` which is going to be the path to your data description, it can also be a subpath eg: `example/README.md` + +You can also add + +- A `description` which is useful if you have more than one dataset for each repo, if not provided we are just going to use the repo description +- A `Name` which is useful if you want to give your dataset a nice name, if not provided we are going to use the junction of the `owner` the `repo` + the path of the README, in the exaple above it will be `fivethirtyeight/data/nba-raptor` + +## Extra commands + +You can also build the project for production with + +``` +npm run build +``` + +And run using the production build like so: + +``` +npm run start +``` -![](https://i.imgur.com/cpKMS80.png)