-
Notifications
You must be signed in to change notification settings - Fork 154
Experiment with Docz #254
base: master
Are you sure you want to change the base?
Experiment with Docz #254
Conversation
You can always install |
ok, I think it's worth switching to Docz. It's easier to write stories, and the end result is nicer / more usable, IMO. Will add a new issue |
Heads-up, if anyone's interested: I'm gonna convert all of our existing stories to docz in the next week or so. I have some good ideas for how this could become our style-guide, making it easier for folks to contribute to the UI :D |
This branch is now properly deployed to Netlify. It looks like the homepage is not defined — should we put something there? |
Yep, I'm on it. I'm excited to treat Docz as more of a "style guide". It should help developers understand how to contribute to the UI, not just be a component library that shows what props are available (although it should do that too). So the homepage will include some info about what it's for, and links to common UI pieces. |
@j-f1 it looks like client-side nav links aren't respected (the link you provided is dead, since netlify doesn't know to redirect that URL to the homepage). Is there a way to set up Netlify to handle client-side navigation? |
@joshwcomeau Is it handled by a router? Perhaps this will help. |
All fixed @joshwcomeau! I used a similar technique to the one @melanieseltzer suggested, but I put it in the |
@joshwcomeau I've modified the structure of the docz a bit and added an index route. Nothing pushed yet - it's just locally. If you like I can push it to docz branch. The content of index page I really like the new docs from react-spring with docz. Maybe we can do it similar but I think we need more structure like in my screenshot above. I'd also like to help to port the storybook stories to docz. What do you think can we merge the basic setup from here to master and create an new issue for tracking the work? |
Prettier supports MDX now 🎉 |
I think it's safe to say that docz and MDX are here to stay. This PR will need to be rebased and brought up to speed with EDIT: There have been some big changes to docz in the last few weeks, and it looks like a few things are required to move forward with this PR:
EDIT 2: Currently, there's no way to have 3rd+ layer nested menu items, so we'll go with a flatter structure for now and track progress here. EDIT 3: The EDIT 4: Both Flow and styled-components currently require some extra config to work correctly with the |
@superhawk610 @AWolf81 Alright, lingering Storybook stories have been converted, and cleaned things up a bit (also added the logo!). Had to add Docz-specific components ( Is there anything you think we could improve upon before a merge? |
@melanieseltzer Looks great. Well done. 👍 I'll do a review later today. For the styling I have one small point - I think it would look better if the Guppy logo is centered in the sidebar. What do you think? In the docz I've noticed that in ProjectIconSelection selecting an icon is not working. It would be great if the selection is working. It would be also great if in the index page there would be a short explanation how to add new Docz stories so new devs are getting an idea where and how to add them. Just adding an small example Any ideas why Circle CI is failing? I've tried to re-build but Flow is failing. I thinks it's a CircleCI issue and not with our code. |
Agreed, centered logo looks better, updated it + expanded the getting started info per your suggestions 👍 Will punt on selecting an icon on click for ProjectIconSelection, was also thinking it could be good to show. I'm also confused why Flow is failing in CircleCI, it looks like it's also happening in #374 as well. No problems locally so this is confusing... |
@@ -26,6 +26,9 @@ export default { | |||
p, a, h1, h2, h3, h4, table { | |||
line-height: 1.6; | |||
} | |||
.bXQPyO, .iCcihC { |
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.
@AWolf81 I'm not sure if it's too fragile to target SC classes, but I'm not sure if Docz has a setting for overriding logo styles 🤔
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.
Yes, I think that's a bit fragile.
Maybe we can create a custom Page
component and a Sidbar
component to change the styling. Not sure how to do this but the following migration guide looks interesting.
But I think we can add a comment to that style and improve this later.
Unfortunately, I don't have any suggestions as to how to resolve the Flow CI issue, but I did experience it quite a bit when actively working on this project (especially on Windows). I could never reliably reproduce it but it cropped up every other day or so and nothing consistently solved it (nuking node_modules, using global/local Here is a thread dating back almost 4 years showing that this issue continues to crop up. The common response is "mismatched global local versions" but I don't know how that could be the case in CI. Maybe we need to bump the |
@superhawk610 I'm running out of ideas - I've tested some of the comments from this issue but with-out success. I've tried:
On Windows it's also really slow for me and VS code liniting is disabled as two running servers are a problem for flow. I think converting to Typescript is probably a pretty heavy task as we would have to modify many files - not sure if it's worth it. But would be an idea if we can't fix the flow issue. [Edit]: I think Netlify is failing because I've updated the |
Should fix Flow failing on CircleCI because Flow is trying to cosume too many virtual servers.
@superhawk610 thanks for pointing to that issue. I think settings the max workers fixed it - not sure why. Next we need to check why Flow is failing - is it because of the previous |
@AWolf81 looks to be a type error, I'll see if I can patch it. EDIT: Alright, that got it. What should we do about the coverage? I wouldn't imagine Docz stuff should really be considered in coverage. |
Codecov Report
@@ Coverage Diff @@
## master #254 +/- ##
=========================================
- Coverage 58.83% 57.93% -0.9%
=========================================
Files 158 165 +7
Lines 3357 3409 +52
Branches 467 471 +4
=========================================
Hits 1975 1975
- Misses 1179 1227 +48
- Partials 203 207 +4
|
@superhawk610 yes, we can exlclude it from coverage by updating this line in What do you think should we revert the change with |
I believe |
@AWolf81 I got the project icon selection working, let me know what you think? Btw, |
I wanted to check Docz but my build with On first try it complains about missing That's also mentioned in this issue but the React dependency seems correct. I also tried to reinstall But still not working.
I also tried Docz@next but that failed with a build error |
Hey all ! I'm the maintainer of docz and a big fan of guppy ! I'd love to help you get setup quickly with docz v2 if you're still interested. I can open a PR to the Sounds good ? cc @joshwcomeau |
Hey @rakannimer, that sounds awesome! We first opened this branch right around the time Briefly checking the status of some of the aforementioned issues seems to indicate that most of them have been resolved, which is great! I remember one of the biggest issues we had is that Additionally, do you think we'll be able to use |
Hey @superhawk610 Thanks for the quick reply ! I'll answer your concerns below as best as I can.
Smart move, it took us quite a bit of time to move from 2.0 release candidates to a solid v2. We're still discovering and fixing bugs of course, but hopefully nothing too major or blocking and we setup e2e tests and CI which will help us keep moving fast with confidence !
docz should understand flow types just as well as typescript ones, I just tested out the latest version with the flow example and it worked as expected. If for some reason, it doesn't recognize the types in this repo than it's probably a bug that we will definitely fix 👍
To the best of my knowledge docz v2 doesn't have a dependency on styled-components, so we should be all right using v3 but I will give this a try to confirm.
This was fixed starting from 2.2.1-alpha.1 and the Example : https://github.com/doczjs/docz/tree/master/examples/styled-components |
Docz is an alternative to Storybook. It uses MDX, which is a cross between Markdown and JSX, and it's really nice for this kind of thing.
I gave it a quick try with our Button component, and I quite like it:
![screen shot 2018-09-17 at 9 22 26 am](https://user-images.githubusercontent.com/6692932/45625586-3a6fdd00-ba5b-11e8-847d-86a844fb78f6.png)
I uploaded it to Surge, play with it here: http://guppy-docz.surge.sh/src-components-button-stroke-button
Pros:
Cons:
.mdx
.Really curious what y'all think. I think I'm leaning towards Docz, but it's not a strong feeling. I also expect Docz might improve a lot over the next few months, so maybe we can revisit this later?