From 7516499fc69931a4ced2cba13229823cd0b0839c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Renato=20de=20Le=C3=A3o?= Date: Fri, 22 Feb 2019 11:54:09 +0000 Subject: [PATCH] Fix documentation typos and instructions - add references to #10 --- README.md | 104 +++++++++++++++++++++---------- scss/qnorr.scss | 16 ++--- scss/tools/mixins/_mx.media.scss | 13 +--- 3 files changed, 77 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index acf684b..849d648 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,106 @@ -A style agnostic, slightly opinionated, style seasoning to bootstrap your projects. +## Documentation + +> If it’s not documented, it doesn’t exist. Documentation should become the default – an integrated part of the development process. +> — Miriam Suzanne + +[See full documentation](https://whitesmith.github.io/qnorr-styles/) ## install -Install via `npm`. +Install via `npm` or `yarn`. + ```shell -yarn add @whitesmith/@whitesmith/qnorr-styles +yarn add @whitesmith/qnorr-styles ``` + + ## usage -**at your `main.scss`** +**at your `{main,index,app}.scss`** ```scss @import "path/to/node_modules/@whitesmith/qnorr-styles/scss/qnorr"; -or if your using a bundler with alias for modules (webpack) -@import "~@whitesmith/qnorr-styles/scss/qnorr" + +// or if your using a bundler with alias for node_modules (webpack / parcel) +@import "~@whitesmith/qnorr-styles/scss/qnorr"; + +// if your using node_sass and defined a custom importer or includePaths +@import "@whitesmith/qnorr-styles/scss/qnorr"; ``` **at your entry file `index.js`** ```javascript import "@whitesmith/qnorr-styles"; // this will import qnorr.css from dist/qnorr.css - -// you can also import sass directly if your bunlder is configure to handle it -import "@whitesmith/qnorr-styles/scss/qnorr.scss; - -const someJsFunction = _ => { - ... -} ``` -### Documentation - -> If it’s not documented, it doesn’t exist. Documentation should become the default – an integrated part of the development process. -> — Miriam Suzanne -[See full documentation](https://whitesmith.github.io/qnorr-styles/) +## Customizing +Want a custom flavour? Go the sassy way. +
+ _"~" is an alias path to `node_modules` and can be different in your system_ +
-### Customizing -Choose your seasonings ```scss -// Required +//// +/// CONFIGURATION +//// + +// at your {main, index, app}.scss file all your config variables overrides; +$qnorr-grid-columns-number: 10; + +// import settings to be overriden by the configuration above; @import "~@whitesmith/qnorr-styles/scss/settings"; -@import "~@whitesmith/qnorr-styles/scss/tools"; - -// optional external dependency -@import "~normalize.css/normalize.css"; -// Optional (check all modules available at scss/** ) -@import "~@whitesmith/qnorr-styles/scss/base/reset"; -@import "~@whitesmith/qnorr-styles/scss/objects/media"; -@import "~@whitesmith/qnorr-styles/scss/utilties/spacers"; + + +///// +/// TOOLING +/// +/// [1] - in perfect world this would also import qnorr-styles required dependencies +/// (mappy-breakpoints), but we're not in a perfect world so check issue#10 +/// for why we decide to not include it by default for now +/// +/// [2] - You can also import individual function and mixins, but then you have +/// check their dependencies on documentation, since there's no output code +/// it makes little sence to do it. It's possible. But not practical. +//// +@import "~mappy-breakpoints/_mappy-breakpoints"; // [1] required +@import "~@whitesmith/qnorr-styles/scss/tools"; // [2] all functions and mixins + + +//// +/// OOCSS MODULES +/// +/// ready to use OOCSS elements, generated with your config +/// [3] - Similar [1], not influenced by any configuration +//// + +@import "~normalize.css/normalize.css"; // [3] +@import "~@whitesmith/qnorr-styles/scss/global/_g.resets"; +@import "~@whitesmith/qnorr-styles/scss/objects/_o.media"; +@import "~@whitesmith/qnorr-styles/scss/objects/_o.grid"; +@import "~@whitesmith/qnorr-styles/scss/objects/_o.skeleton"; +@import "~@whitesmith/qnorr-styles/scss/utilities/_u.spacers"; +@import "~@whitesmith/qnorr-styles/scss/utilities/_u.widths"; +@import "~@whitesmith/qnorr-styles/scss/utilities/_u.text"; ``` ## Dependencies qnorr ships with two dependencies by default: -- [mappy-breakpoints](https://github.com/zellwk/mappy-breakpoints) to handle our media query needs (required, no-opt-out) -- [normalize.css](https://github.com/necolas/normalize.css/) to reset browser styles (optional import if you're using scss verison) +- [mappy-breakpoints (required)](https://github.com/zellwk/mappy-breakpoints) to handle our media query needs +- [normalize.css (optional)](https://github.com/necolas/normalize.css/) to reset browser styles (optional import if you're using scss verison) + +Note: read more about [sass module dependency import issues here](https://github.com/whitesmith/qnorr-styles/issues/10); + ## Developing - We use [gulp@4.0^](https://gulpjs.com/) to build the library (legacy CLI scripts are also available but they are way difficult to maintain). -- We use [parcel](https://parceljs.org/) and [posthtml plugins](https://github.com/posthtml/posthtml) to build a basic site located under `/site` folder. If you want to help build a real documentation site, create a `docs` folder and let's use the monorepo approach — docs building are separated from library and we can use any tool to make it happen (vuepress, gitbook, etc.), suggestions are welcomed. +- We use [sassdoc](https://sassdoc.com/) to build and generate documentation `/docs` folder. Head to the site to learn how to use it, or just check any source file for an example, you'll get it super fast. A pretty custom theme is possible but let's leave it for version 2. +- We use [parcel](https://parceljs.org/) and [posthtml plugins](https://github.com/posthtml/posthtml) to build a basic site located under `/site` folder so you can play around with the framework. Developing ``` -# watch mode for qnorr, dev server for demo site +# watch mode for qnorr will also start a server for documentation yarn run start ``` diff --git a/scss/qnorr.scss b/scss/qnorr.scss index 5c7f850..08c037f 100644 --- a/scss/qnorr.scss +++ b/scss/qnorr.scss @@ -11,15 +11,9 @@ /// @author Whitesmith /// @link https://github.com/whitesmith/qnorr-styles /// -/// @todo [1] investigate why gulp-sass includePaths is -/// not working and we have to ref node modules with -/// this ugly paths -/// -/// @todo [2] solving includePaths might actual break -/// npm deploy because of dependencies might be loded by other bundlers -/// although we can advise to not import qnorr.scss directly but only its -/// modules, and import dependencies from node_modules directly -/// think about it. +/// @todo [1] watching sass developments on dynamic imports +/// so we can specify configurable import paths to our dependencies +/// https://github.com/whitesmith/qnorr-styles/issues/10 /// //// @@ -27,8 +21,8 @@ // SETTINGS @import "settings/index"; -// TOOLS [2] -@import "../node_modules/mappy-breakpoints/_mappy-breakpoints.scss"; //[1] +// TOOLS +@import "../node_modules/mappy-breakpoints/_mappy-breakpoints.scss"; // [1] @import "tools/index"; /// GLOBAL diff --git a/scss/tools/mixins/_mx.media.scss b/scss/tools/mixins/_mx.media.scss index b2b297d..1607196 100644 --- a/scss/tools/mixins/_mx.media.scss +++ b/scss/tools/mixins/_mx.media.scss @@ -1,16 +1,5 @@ -//// -/// The holy grail of layout reused patterns -/// Figure + text + alignment -/// -/// @group GroupName -/// @author AuthorName -/// -/// @link http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/ -/// @todo naming, should we namespace o use more verbose media-object -//// - - /// +/// @group Tools /// Creates the media object wrapper /// @mixin media {