ui: Remove storybook, add docfy#9831
Merged
Merged
Conversation
added 9 commits
February 25, 2021 13:33
Contributor
|
🤔 Double check that this PR does not require a changelog entry in the |
Contributor
|
🍒 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
docfyand 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
docfyconfiguration and adding a:to our code blocks, we'd solved our missing feature 🎉
This PR removes
storybookand addsdocfyand usesdocfyto 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
runInDebugstatesUses 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
runInDebugstatements 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.