ember-learn/ember-jsonapi-docs

Bug - Parsing of new decorators doesn't work

jenweber opened this issue · 11 comments

jenweber commented

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 commented

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.

sivakumar-kailasam commented

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 commented

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!)

  • 👍1
pzuraq commented

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

  • 🎉1
sivakumar-kailasam commented

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 commented

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 commented

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 commented
pzuraq commented

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 commented