From fb1bec9b10f1f0e548080e1a6fdb6a46120786a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Egelund-M=C3=BCller?= Date: Fri, 26 May 2023 00:19:57 +0200 Subject: [PATCH] Adapt docs for refactored examples (#2505) * Adapt docs for refactored examples * Make Github steps simpler * Fix broken link in sources tutorial --- README.md | 14 +-- docs/docs/deploy/existing-project.md | 24 +---- docs/docs/develop/import-data.md | 2 +- docs/docs/end-to-end.md | 51 ---------- docs/docs/get-started.md | 51 ++++++++++ docs/docs/home.md | 9 +- docs/docs/reference/cli-cheat-sheet.md | 98 ------------------- .../reference/project-files/_category_.yml | 2 +- docs/docs/share/roles-permissions.md | 2 +- .../{share-rill.md => user-management.md} | 0 runtime/connectors/gcs/gcs.go | 2 +- runtime/connectors/s3/s3.go | 2 +- 12 files changed, 68 insertions(+), 189 deletions(-) delete mode 100644 docs/docs/end-to-end.md create mode 100644 docs/docs/get-started.md delete mode 100644 docs/docs/reference/cli-cheat-sheet.md rename docs/docs/share/{share-rill.md => user-management.md} (100%) diff --git a/README.md b/README.md index caf0901cc82..45a9ac6ac8e 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,23 @@ Rill makes it effortless to transform your datasets with SQL and create powerful ``` curl -s https://cdn.rilldata.com/install.sh | bash -rill start my_rill_project +rill start my-rill-project ``` ![home-demo](https://github.com/rilldata/rill-developer/assets/5587788/49d17e80-5f27-408c-bbc9-fdbff7b6b627 "829237828") - Rill's design principles: +Rill's design principles: - _**Feels good to use**_ – powered by Sveltekit & DuckDB = conversation-fast, not wait-ten-seconds-for-result-set fast - _**Works with your local and remote datasets**_ – imports and exports Parquet and CSV (s3, gcs, https, local) - _**No more data analysis "side-quests"**_ – helps you build intuition about your dataset through automatic profiling - _**No "run query" button required**_ – responds to each keystroke by re-profiling the resulting dataset - _**Radically simple interactive dashboards**_ – thoughtful, opinionated interactive dashboards defaults to help you quickly derive insights from your data -- _**Dashboards as code**_ – each step from data to dashboard has versioning, git sharing, and easy project rehydration +- _**Dashboards as code**_ – each step from data to dashboard has versioning, Git sharing, and easy project rehydration ## We want to hear from you -You can [file an issue](https://github.com/rilldata/rill-developer/issues/new/choose) or reach us in our [Rill discord](https://bit.ly/3unvA05) channel. Please abide by the [rill community policy](https://github.com/rilldata/rill-developer/blob/main/COMMUNITY-POLICY.md). - +You can [file an issue](https://github.com/rilldata/rill-developer/issues/new/choose) or reach us in our [Rill discord](https://bit.ly/3unvA05) channel. Please abide by the [community policy](https://github.com/rilldata/rill-developer/blob/main/COMMUNITY-POLICY.md). ## Legal -By downloading and using our application you are agreeing to the [Privacy Policy](https://www.rilldata.com/legal/privacy) and [Rill Terms of Service](https://www.rilldata.com/legal/tos). - - - +By downloading and using our application you are agreeing to the [Privacy Policy](https://www.rilldata.com/legal/privacy) and [Rill Terms of Service](https://www.rilldata.com/legal/tos). diff --git a/docs/docs/deploy/existing-project.md b/docs/docs/deploy/existing-project.md index ff59ba3a579..00ab515a2f9 100644 --- a/docs/docs/deploy/existing-project.md +++ b/docs/docs/deploy/existing-project.md @@ -19,26 +19,8 @@ graph LR; Rill Cloud connects to a repository on Github containing a Rill project, and continuously deploys that project on every push. Therefore, your project must be on Github before you deploy it to Rill. -Follow these steps to push your project to Github: - -1. Initialize `git`: -``` -git init -``` -2. Add and commit the project files: -``` -git add . -git commit -m "Initial commit" -``` -3. Create a new Github repository on Github: [https://github.com/new](https://github.com/new) -4. Link `git` to the remote repository -``` -git remote add origin https://github.com/your-account/your-repo.git -``` -5. Push your repository to Github -``` -git push -u origin main -``` +- If your project is not yet on Github, follow the steps on [https://github.com/new](https://github.com/new) to create a new repository and push your project files to it. +- If your project is already on Github, make sure you have permission to grant access to it. If you're deploying a project controlled by someone else, first fork or copy it to a repository in your account. ## Deploy to Rill Cloud @@ -68,7 +50,7 @@ rill project reconcile --refresh # Change your production branch -By default, Rill deploys from the [default branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch) of your git repository. You can change this to any branch you want. +By default, Rill deploys from the [default branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch) of your Git repository. You can change this to any branch you want. To deploy your project from a different branch, run the following command: diff --git a/docs/docs/develop/import-data.md b/docs/docs/develop/import-data.md index b0f54dd3ef9..973bc7901ca 100644 --- a/docs/docs/develop/import-data.md +++ b/docs/docs/develop/import-data.md @@ -105,7 +105,7 @@ If you do not have the AWS CLI installed and authenticated, follow these steps: 3. If your organization does not have SSO configured: - a. Follow the steps described under [How to create an AWS service account using the AWS Management Console](#how-to-create-an-aws-service-account-using-the-aws-management-console), which you will find below on this page. + a. Follow the steps described in [How to create an AWS service account using the AWS Management Console](../deploy/credentials/s3.md#how-to-create-an-aws-service-account-using-the-aws-management-console) in our tutorial for [Amazon S3 credentials](../deploy/credentials/s3.md). b. Run the following command and provide the access key, access secret, and default region when prompted (you can leave the "Default output format" blank): ``` diff --git a/docs/docs/end-to-end.md b/docs/docs/end-to-end.md deleted file mode 100644 index ed7ca5dac61..00000000000 --- a/docs/docs/end-to-end.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Get started -sidebar_label: Get started -sidebar_position: 10 ---- - -This tutorial is a step by step guide that will help you install Rill, ingest source data, and deploy a secure dashboard application online. - - -## Install Rill - -You can install `rill` on Mac or Linux ([WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for Windows users) using our installation script: - -``` -curl -s https://cdn.rilldata.com/install.sh | bash -``` - -## Create your project - -Checkout our example project files from Github and start the project with Rill: - -``` -git clone https://github.com/rilldata/rill-developer-example.git -rill start rill-developer-example -``` -The Rill web app runs locally at `http://localhost:9009`. - - -## Transform your data - -Data [transformations in Rill](../develop/sql-models) are composed of SQL SELECT statements that model source data. - - -## Deploy your dashboard - -You can [deploy](../deploy/existing-project) any Rill project with a dashboard to an authenticated hosted endpoint by running: - -``` -rill deploy -``` - - -## Share your dashboard - -Projects on Rill are private by default. To invite others to explore your project, run: -``` -rill user add -``` -## We want to hear from you - -You can file an issue in [this repository](https://github.com/rilldata/rill-developer/issues/new/choose) or reach us in our [Discord channel](https://bit.ly/3unvA05). diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md new file mode 100644 index 00000000000..8c8e3628f70 --- /dev/null +++ b/docs/docs/get-started.md @@ -0,0 +1,51 @@ +--- +title: Get started +sidebar_label: Get started +sidebar_position: 10 +--- + +This tutorial is a step by step guide that will help you install Rill, ingest source data, and deploy a dashboard online. + +## Install Rill + +Install `rill` on Mac or Linux ([WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for Windows users) using the installation script: + +``` +curl -s https://cdn.rilldata.com/install.sh | bash +``` + +## Create your project + +Start a new Rill project: + +``` +rill start my-rill-project +``` + +The Rill web app runs locally at `http://localhost:9009` and will create code files in the `my-rill-project` directory. + +## Load and transform data + +On the welcome screen, initialize an example project or load up Rill with your own data. Use the app to develop data models and dashboards. + +## Deploy your dashboard + +You can deploy any Rill project with a dashboard to an authenticated hosted endpoint: + +1. Create a new Github repository on [https://github.com/new](https://github.com/new) and push your `my-rill-project` directory to it +2. Setup continuous deployment from Github to Rill Cloud: + ``` + cd my-rill-project + rill deploy + ``` + +## Share your dashboard + +Projects on Rill Cloud are private by default. To invite others to explore your project, run: +``` +rill user add +``` + +## We want to hear from you + +You can file an issue [on GitHub](https://github.com/rilldata/rill-developer/issues/new/choose) or reach us in our [Discord channel](https://bit.ly/3unvA05). diff --git a/docs/docs/home.md b/docs/docs/home.md index dcd934c8867..4f2a59f8022 100644 --- a/docs/docs/home.md +++ b/docs/docs/home.md @@ -9,23 +9,22 @@ Rill is the fastest path from data lake to dashboard. Download Rill to start mo ``` curl -s https://cdn.rilldata.com/install.sh | bash -rill start my_rill_project +rill start my-rill-project ``` ![home-demo](https://github.com/rilldata/rill-developer/assets/5587788/49d17e80-5f27-408c-bbc9-fdbff7b6b627 "829237828") - Rill's design principles: +Rill's design principles: - _**Feels good to use**_ – powered by Sveltekit & DuckDB = conversation-fast, not wait-ten-seconds-for-result-set fast - _**Works with your local and remote datasets**_ – imports and exports Parquet and CSV (s3, gcs, https, local) - _**No more data analysis "side-quests"**_ – helps you build intuition about your dataset through automatic profiling - _**No "run query" button required**_ – responds to each keystroke by re-profiling the resulting dataset - _**Radically simple interactive dashboards**_ – thoughtful, opinionated interactive dashboards defaults to help you quickly derive insights from your data -- _**Dashboards as code**_ – each step from data to dashboard has versioning, git sharing, and easy project rehydration +- _**Dashboards as code**_ – each step from data to dashboard has versioning, Git sharing, and easy project rehydration ## We want to hear from you We always appreciate hearing from our users and welcome any questions, comments, or concerns you may have. To get in touch with us, there are two options available: 1. _**File an issue**_: If you have encountered a bug or have a feature request, please [file an issue](https://github.com/rilldata/rill-developer/issues/new/choose) on our GitHub page.You can 2. _**Join our Discord channel**_: For general inquiries or if you need help getting started with Rill, we encourage you to join our [Discord community](https://bit.ly/3unvA05). -Please abide by the [rill community policy](https://github.com/rilldata/rill-developer/blob/main/COMMUNITY-POLICY.md). - +Please abide by the [community policy](https://github.com/rilldata/rill-developer/blob/main/COMMUNITY-POLICY.md). diff --git a/docs/docs/reference/cli-cheat-sheet.md b/docs/docs/reference/cli-cheat-sheet.md deleted file mode 100644 index 1ac830566a1..00000000000 --- a/docs/docs/reference/cli-cheat-sheet.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: CLI cheat sheet -description: Start and manage Rill using the command-line interface (CLI) -sidebar_label: CLI cheat sheet -sidebar_position: 10 ---- - -## Start a new project - -In any empty folder, simply run: - -```bash -rill start -``` - -to initialize an empty project and open the Rill web app on [http://localhost:9009](http://localhost:9009). You can use the web app to define data sources, data models and dashboards. - -## Help menu - -To see usage information about all the available CLI commands, run: - -```bash -rill -``` - -For any sub-command, you can always pass `--help` to output detailed usage information. For example: - -```bash -rill start --help -``` - -outputs detailed information about the flags you can pass to `rill start`. - -## Initializing an empty project - -In any empty folder, run - -```bash -rill init -``` - -to initialize an empty project. - -## Initializing an example project - -We recommend following our [quick start](../end-to-end.md) to experience how well Rill ties together with Git. However, Rill also bundles some built-in examples to help you get started quickly. To initialize the default example, run: - -``` -rill init --example -``` - -To view a list of all built-in example projects: - -``` -rill init --list-examples -``` - -To use a non-default example, pass it as a parameter to `--example`: - -``` -rill init --example=sf_props -``` - -## Running Rill in another directory - -You can explicitly specify a project folder outside of the current folder using the `--project` option: - -``` -rill init --project /path/to/project -rill source add /path/to/data.parquet --project /path/to/project -rill start --project /path/to/project -``` - -## Import a local data file - -You can create a local file source by running: - -``` -rill source add /path/to/data.parquet -``` - -See [Import data](../develop/import-data.md) for more details. - -### Override the source name - -By default the source name will be a sanitized version of the dataset file name. You can specify a name using the `name` command. - -``` -rill source add /path/to/data.parquet --name my_source -``` - -## Dropping a source - -If you have added a source to Rill that you want to drop, run: - -```bash -rill source drop my_source -``` diff --git a/docs/docs/reference/project-files/_category_.yml b/docs/docs/reference/project-files/_category_.yml index c41e6e4d009..70a3beaeadb 100644 --- a/docs/docs/reference/project-files/_category_.yml +++ b/docs/docs/reference/project-files/_category_.yml @@ -1,4 +1,4 @@ -position: 20 +position: 10 label: Project files collapsible: false collapsed: false diff --git a/docs/docs/share/roles-permissions.md b/docs/docs/share/roles-permissions.md index b5ffb081878..d3146a90bde 100644 --- a/docs/docs/share/roles-permissions.md +++ b/docs/docs/share/roles-permissions.md @@ -7,7 +7,7 @@ sidebar_position: 30 Access permissions in Rill Cloud are organized into roles at the organization and project level. It is usually sufficient to grant access at the organization-level because those permissions are inherited for projects by default. -For information about granting, revoking and changing roles, see [Share with others](./share-rill.md). +For information about granting, revoking and changing roles, see [Share with others](./user-management.md). ## Role inheritance diff --git a/docs/docs/share/share-rill.md b/docs/docs/share/user-management.md similarity index 100% rename from docs/docs/share/share-rill.md rename to docs/docs/share/user-management.md diff --git a/runtime/connectors/gcs/gcs.go b/runtime/connectors/gcs/gcs.go index 530de40dc71..8178acaadb3 100644 --- a/runtime/connectors/gcs/gcs.go +++ b/runtime/connectors/gcs/gcs.go @@ -31,7 +31,7 @@ var errNoCredentials = errors.New("empty credentials: set `google_application_cr var spec = connectors.Spec{ DisplayName: "Google Cloud Storage", Description: "Connect to Google Cloud Storage.", - ServiceAccountDocs: "https://docs.rilldata.com/connectors/gcs", + ServiceAccountDocs: "https://docs.rilldata.com/deploy/credentials/gcs", Properties: []connectors.PropertySchema{ { Key: "path", diff --git a/runtime/connectors/s3/s3.go b/runtime/connectors/s3/s3.go index ca5d0329a19..d8cabbf7a28 100644 --- a/runtime/connectors/s3/s3.go +++ b/runtime/connectors/s3/s3.go @@ -29,7 +29,7 @@ func init() { var spec = connectors.Spec{ DisplayName: "Amazon S3", Description: "Connect to AWS S3 Storage.", - ServiceAccountDocs: "https://docs.rilldata.com/connectors/s3", + ServiceAccountDocs: "https://docs.rilldata.com/deploy/credentials/s3", Properties: []connectors.PropertySchema{ { Key: "path",