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

Bug - Parsing of new decorators doesn't work #75

Open
jenweber opened this issue Oct 25, 2019 · 11 comments
Open

Bug - Parsing of new decorators doesn't work #75

jenweber opened this issue Oct 25, 2019 · 11 comments
Assignees

Comments

@jenweber
Copy link
Contributor

jenweber commented Oct 25, 2019

In the latest work for Ember Octane, there are some new decorators that don't parse correctly. For example, if you use @tracked in a code sample, it doesn't render. However, we have used decorators in other parts of the guides successfully. It also seems that the processing itself hangs.

See https://github.com/ember-learn/ember-jsonapi-docs/blob/5c3d9d81107ef4ec8e1fe016de8be3c3c214121b/lib/fix-borked-yuidoc-files.js for how this was handled for other cases.

@jenweber
Copy link
Contributor Author

Debugging strategy:

If the initial parsing does not succeed, you can comment out the work being done in a file called fix-borked-yuidocs.js or something like that. Then parsing will finish, and when you serve it locally, you will see broken code blocks wherever decorators are used

Overall flow:

Set the version number in ember.js package.json to something fake, like 4.0.0. Then...

cd ember-jsonapi-docs
rm -rf tmp
yarn gen --version 4.0.0 (pseudocode - see Readme for exact command)
yarn server
cd ../ember-api-docs
yarn start:local

Always remove tmp when you make changes.

@MelSumner
Copy link
Member

@rwjblue @pzuraq @chancancode for visibility

@sivakumar-kailasam
Copy link
Member

Digged into this a bit & figured that the reason this doesn't work is because the fix-borked-yuidoc-file script doesn't account for the decorators usage in the example yuidoc tag(when we authored that script, we didn't use example tags). Will add the fix shortly.

@pzuraq
Copy link

pzuraq commented Oct 30, 2019

I'm working on a better fix for this upstream in ember-cli-yuidoc. The borked fix is alright, but it's still results in some data loss and messed up formatting, and is a bit hard to follow (but works pretty well all things considered!)

@pzuraq
Copy link

pzuraq commented Oct 30, 2019

Fix is up here: cibernox/ember-cli-yuidoc#52

@sivakumar-kailasam
Copy link
Member

Thanks @pzuraq!

@rwjblue Once this fix is merged, can we release patch versions of ember & ember-data from 3.10-3.14 with the upgraded ember-cli-yuidoc? This fix would produce better formatted code blocks in the api docs & we'll no longer have to handle the messed up files in this app.

@rwjblue
Copy link

rwjblue commented Oct 30, 2019

We can definitely get 3.12, 3.14, and 3.15-beta's out but I'm not sure about re-releasing patch releases of unsupported versions (3.10, 3.11, and 3.13 are all unsupported).

@pzuraq
Copy link

pzuraq commented Oct 30, 2019

Could we possibly patch the docs directly, without doing a release? I'm not familiar with how the docs artifacts get generated and stored, but if ember-cli-yuidoc does a patch release, we shouldn't need to actually change anything in ember-source or ember-data, in theory, we could just regenerate the docs and publish those (which, tbh, might be a nice thing in general to be able to do for corrections/fixes)

@sivakumar-kailasam
Copy link
Member

sivakumar-kailasam commented Oct 30, 2019 via email

@pzuraq
Copy link

pzuraq commented Oct 30, 2019

Could this be an issue if we ever need to regenerate those docs in the future? We should document what that process looks like, so we know about these versions of Ember where the docs need to manually generated. Either that, or potentially we should keep the other patch as well, specifically for those versions of docs.

@sivakumar-kailasam
Copy link
Member

sivakumar-kailasam commented Oct 30, 2019 via email

@sivakumar-kailasam sivakumar-kailasam removed their assignment Jun 25, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants