-
Notifications
You must be signed in to change notification settings - Fork 4.4k
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
ui: Remove storybook, add docfy #9831
Conversation
🤔 Double check that this PR does not require a changelog entry in the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice cleanup 🔥
🍒 If backport labels were added before merging, cherry-picking will start automatically. To retroactively trigger a backport after merging, add backport labels and re-run https://circleci.com/gh/hashicorp/consul/334156. |
Back in #9049 we added storybook with a view to providing an approach to catalog and work on our components in an isolated manner. Whilst storybook has been installed and used in other projects, its never really sat that well with us:
All in all, whilst it would be great to see storybook in ember/glimmer improving over time it's unfortunately not something that works for us right now. (but we'll be keeping an eye on things as we don't want to rule it out in the future)
To back up a little, a while ago we switched to a nested component structure and started add README files to each components folder (#7448). As they are just plain and simple markdown README files they are completely readable in GitHub, which meant readable docs with no extra effort of providing a way to read them. You can quite easily use GitHub as our documentation site.
The missing feature here is being able to render our Glimmer components live inside the README files.
At the time we just used code blocks so you could at least see the code used to use a component and left this missing feature as a future exercise (at the time storybook was thought to be the potential solution).
Recently we stumbled upon
docfy
and its ember specific addon and decided to give it a try to see how straightforwards it would be to use it to render the code blocks of our README files as live rendered glimmer components.After a few lines of
docfy
configuration and adding a:to our code blocks, we'd solved our missing feature 🎉
This PR removes
storybook
and addsdocfy
and usesdocfy
to render our existing README files.This now means we can keep adding README documentation without commiting any specific format or framework. If we eventually move to storybook then fine, or if we just want to remove docfy for whatever reason then fine - we will still have a full set of README files viewable via GitHub.
Additionally this PR uses our
<App />
component to provide sidebar navigation for all of our component README files, and adds some ember configuration to keep anydocfy
/documentation code out of our production build. Whilst this exclusion configuration works fine, we'll probably improve this and externalize it a bit better at a later date (we have quite a bit of 'debug code' now dotted around and it would nice for it to all be in one place).We also noticed whilst we were doing this that although the older ember documentation for
runInDebug
statesUses of this method in Ember itself are stripped from the ember.prod.js build.
, but that is not actually the case 😬 (or at least not in later versions).I'm not sure exactly when the documentation was updated to remove this statement (or if
runInDebug
statements were ever stripped from prod builds in the first place), but we'll probably need to alter our approach to debug code in general if we want to avoid debug code being included in the payload of production builds. So that will be a good opportunity to think about how we handle 'debug only code' at a more general/global level.Lastly the code here is enough to allow us to keep adding more and more documentation as we go, without adding extra weight to our production build. We'll probably keep moving forwards with the docs pages with some styling tweaks etc.