Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE]: add information about updating jayvee extension in the docs #480

Merged
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions apps/docs/docs/user/intro.md
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall it would be good to add a completely new document (e.g., update.md) that we can link to. That document should include only a documentation on how to update to a new Jayvee version:

  • That you need to update Jayvee and the VSCode extension both
  • The explicit npm install command for that version
  • How to update the VSCode extension
  • How to verify that you have the right jayvee version installed
  • How to verify that you have the right VSCode extension installed

You can then link that new document from here.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created the update.md file and logic.
How can I now link this page without having it in the header or on the menu at the left side ? Couldn't find any example of such a situation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure actually. We use https://docusaurus.io/ so maybe they have something in their docs? I assume it has something to do with the markdown frontmatter / metadata between the dashes, e.g. for intro.md

---
sidebar_position: 1
---

I assume there is some boolean there that hides it from the menu?

Once you have updated the PR so the comments are fixed, you can retrigger the review by the way, then I can have another look :).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not able to find a solution to not have it in the sidebar.
Solutions ? Leave it right under introduction to Jayvee ?

Another option would be a menu point under : Introduction of Jayvee.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I Updated the docs in a way that i think is the best within implementing the update page:
image

Getting started (which is actually the wording I found on 80% of documentations) = the intro page
Update Javee: Information about updating Javee

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rhazn need review on this to resolve the conversation and ask for an overall review of the PR.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you need a review, please re-request a review (top right). But make sure the CI works beforehand, right now it is failing.

Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_position: 1

# Introduction to Jayvee

Jayvee is a domain-specific language (DSL) for data engineering - the cleaning and preprocessing of data for later activities like data science or machine learning. You can use Jayvee to **model an ETL pipeline** and the command-line interpreter to **run the ETL pipeline** on your local machine.
Jayvee is a domain-specific language (DSL) for data engineering - the cleaning and preprocessing of data for later activities like data science or machine learning. You can use Jayvee to **model an ETL pipeline** and the command-line interpreter to **run the ETL pipeline** on your local machine.

## Installation

Expand All @@ -15,6 +15,7 @@ npm install -g @jvalue/jayvee-interpreter
```

You can install a specific version using the `@`-syntax, e.g., version `0.0.17`:

```bash
npm install -g @jvalue/[email protected]
```
Expand All @@ -23,6 +24,10 @@ npm install -g @jvalue/[email protected]

Updating the interpreter is done by reinstalling it using `npm`. Make sure to also update the [VSCode plugin](#vscode-plugin) to match the installed interpreter if you use it.

IMPORTANT: If a new Jayvee update is available, you need to update your Jayvee extension as well.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Your VSCode extension for Jayvee" would be the correct wording.


Extensions and updates can be found [here](https://github.com/jvalue/jayvee/releases/tag/v0.2.0-alpha).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should link to https://github.com/jvalue/jayvee/releases/latest, not to a specific version.


```bash
npm install -g @jvalue/jayvee-interpreter
```
Expand All @@ -47,7 +52,6 @@ Run with **additional debug output**:
jv <file> -d
```


With **runtime parameters**:

```console
Expand All @@ -61,35 +65,37 @@ Print debugging is further configured by the parameters `--debug-granularity` an
```console
jv <file> -d -dg peek
```

The value of the parameter `--debug-granularity` (short `-dg`) can have the following values:
- `peek` to log a short summary, including a small subset of data

- `peek` to log a short summary, including a small subset of data
- `exhaustive` to log a summary, including the full data
- `minimal` to log a summary, including no additional data (default).
To see logs, debugging has to be enabled using the `-d` flag.
To see logs, debugging has to be enabled using the `-d` flag.

```console
jv <file> -d --debug-granularity peek
```

The parameter `--debug-target` (short `-dt`) allows to specify which blocks should be logged for debugging. Separate block names by comma if multiple blocks are targeted. All blocks are logged if the parameter is omitted.

```console
jv <file> -d --debug-granularity peek --debug-target MyExtractorBlock,MySinkBlock
```


## Examples

You can find multiple examples [here](https://github.com/jvalue/jayvee/tree/main/example). Copy them to your local file system and execute them with the `jv` command on your command line (see [usage](#usage)).


## VSCode Plugin

To set up Jayvee locally in VS Code, you need to install the latest Jayvee VS Code extension.
To install the most recent extension, go to our [latest release](https://github.com/jvalue/jayvee/releases/latest)
To install the most recent extension, go to our [latest release](https://github.com/jvalue/jayvee/releases/latest)
and download the `jayvee.vsix` file from the release assets.
Next, go to [this page](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix) and
Next, go to [this page](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix) and
follow the instructions for installing the downloaded extension.

## Troubleshooting

1. Error `structuredClone is not defined`
* Please make sure you use node version 17+.
- Please make sure you use node version 17+.