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

Octane guides review: ensure code examples are complete #583

Closed
mike-north opened this issue Mar 12, 2019 · 5 comments
Closed

Octane guides review: ensure code examples are complete #583

mike-north opened this issue Mar 12, 2019 · 5 comments
Labels

Comments

@mike-north
Copy link
Contributor

The octane guides (#455) are coming along really well!

One thing that we could use some help with is reviewing all markdown "fenced code blocks"

```javascript

```
```handlebars

```

are...

  1. Valid language syntax.

    A good way of checking this is to open up https://babeljs.io/repl and paste a code sample in the left editor pane.

  2. Complete

    Some of them seem to be missing imports, particularly for decorators like @tracked, @action, etc... The good news is, other examples are complete, and will provide an indication of where to import from.

    If examples use something like "..." to provide an excerpt, please make sure it's in a comment, so that if readers copy/paste code into their editor, it's only incomplete and not broken.

@mansona
Copy link
Member

mansona commented Mar 12, 2019

Here is a tool that we used to verify all of the code blocks during the AngleBrackets migration: #589

I don't know how useful it would be to you but it's there if you need it 🎉

@ghost
Copy link

ghost commented Mar 12, 2019

Here are 2 aspects of this I found while working against the octane branch:
#565
#579
I think they also apply to master.

@ghost
Copy link

ghost commented Mar 16, 2019

I think there are a couple approaches with short and long term approaches.

  1. integrate the extraction script and pass relevant blocks to eslint
  2. Prettier supports parsing markdown and formats embedded snippets. We could run it automatically if the opinions align. To see the changes, try running:
npx prettier --parser markdown --single-quote --write "guides/release/**/*.md"

I did try integrating prettier with the extractCode snippet and found it provides helpful errors for some invalid code snippets. Some of the failures were false positives though.
I think full prettier integration could make sense at some point, so perhaps for initial review we could focus on making the extract script provide useful output and possibly copies of the files with the corrected changes.

@ghost ghost mentioned this issue Mar 16, 2019
@jenweber
Copy link
Contributor

Closed by a dozen or so PRs ahead of EmberConf

@jenweber
Copy link
Contributor

Thanks everyone for your help!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

4 participants