-
Notifications
You must be signed in to change notification settings - Fork 1
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
Evaluate SassDocs for use as possible documentation generation, as well as backstop regression testing. #29
Comments
Having given sassdoc a go, I've found documenting all sass functions etc with sassdoc very compelling. The vscode plugin does some nice hinting and sassdocs own documentation is quite good and largely mimics JSDocs. I also like how easy it generates documentation on things like mixins, functions, maps etc, and has awesome search functionality baked in. This said, the way sassdocs works means that out of the box, it doesn't appear to generate a static route for each unit or group (happy to be corrected here). With patternlab for example, in the generated documentation there is a Another hurdle is that sassdocs ecosystem is rather dormant at the moment, which is likely a byproduct of the lead developers have busy lives of their own and have moved on, a symptom of the maturity of the project that is largely feature complete, and/or the result of the community at large generally adopting tools other then Sass, or different documentation mechanisms.
Regardless, while I cannot justify two documentation mechanisms, I see little disadvantage to not adopting sassdoc for the inline docs of the project going forward. |
The documentation generator for sassdocs isn't quite as versatile as I would like, as much of our css is generated. One limitation is that
The results are not a great start for something like a functional lib like Tachyons. While the above isn't entirely unexpected for Sass centric documentation, it isn't as readable as what Tachyons already has and doesn't appear flexible enough to come close to being able to generate it. It is worth examining how much functionality can be imparted with a theme, and Herman also from OddBird seems to do just this. OddBird has also created [Accoutrement] for 'Integrated design-system management in Sass'. It appears to be a suite of tools which help to process design tokens. It may be worth also considering using a fork of scss-comment-parser to pump scss comments. Interestingly both both PatternLab Docs and OddBird.net are built with 11ty |
There is also a lack of deep nesting within groups, which is limiting as we have lots of categorisation. Variables and Maps don't have limited documentation mechanisms #389 Nested functions, mixins maps etc are difficult or impossible to document cleanly. |
No description provided.
The text was updated successfully, but these errors were encountered: