docs: improve theming documentation

[brandyscarney]

So I don't know the best way this can be achieved, but it would be good to improve the documentation behind which Sass variables control what.

A great recommendation by @alexbainbridge:

Would be great to have some component "screenshots" with arrows pointing to aspects that different scss values control. With a number of elements taking scss from different components, this would make it easier to know what controls what. i.e. pretty much what you have done above.

I'm not sure how maintaining this would be, but it is something to think about. Please add any thoughts on this here! cc @adamdbradley @mhartington @jgw96 @danbucholtz

[mhartington]

Idea: create a dgeni process that can parse comments in scss files.

// Action Sheet
// --------------------------------------------------

// @description action-sheets default width
$action-sheet-width:                             100% !default;
// @description action-sheets maximum width
$action-sheet-max-width:                         500px !default;

We already have dgeni documenting APIs, seems fitting that it would do scss too.

[alexbainbridge]

Thanks Brandy!

While I defer to yourselves, even if this was manual, if errors crept in, I am sure the community would correct, hence either manual or automated would provide sufficiently useful, accurate, information and be appreciated by the wider users

[brandyscarney]

Another idea is to do something similar to Foundation's Customize With Sass sections where it lists the variables related to each component and what they do.

[brandyscarney]

Also need to clarify that a base and contrast must be added to the $colors map: https://github.com/driftyco/ionic/blob/master/CHANGELOG.md#theming-with-base--contrast-colors---5445

[perrygovier]

Brandy and I just chatted about this.

I'd like to add an new set of documentation attributes. Something like @styleFile or @mdStyles. Then a dgeni processor can load those SCSS files and get the necessary descriptions and data. We can use a lib like https://github.com/SassDoc/sassdoc if we need help getting data out of the file.

With the data, we can generate a new section in the applicable components.

[mhartington]

@perrygovier this is great.

[brandyscarney]

Do you think we could just have one attribute like @styles and then use that URL but append the mode to get the other files? I'm just thinking if we add another mode in the future (not planned but you never know) we'll have to manually go through each component and add it.

[perrygovier]

I need to verify, but if your naming is consistent everywhere, we can just check to see if the files exist and not need any new attribute at all.

[brandyscarney]

Generally it is like the following (using range as an example):

range.scss
range.ios.scss
range.md.scss
range.wp.scss

but there are cases where there is just the component.scss file (e.g. refresher), or there is no component.scss file and only the mode specific ones (.e.g. radio).

[brandyscarney]

I started adding documentation for the sass variables (see tabs.ios for example) so I'll just start adding them as I make changes and then when you guys let me know how we should link these to the API I can add that. I'm thinking we have a Sass Variables section, similar to how input properties is set up, that shows which variables affect all modes (if *.scss exists) and then a toggle for the different modes ios, md, and wp (if those exist).

[brandyscarney]

I've been discussing this with @briandennis. The syntax will look like the following:

/// @prop - Padding on the tab button
$tabs-md-tab-padding:                  8px 0 10px 0 !default;

and that will automatically add the name, default, and description of the variable to the API docs. The tabs component has this added now: ionic-team/ionic-framework@b7c4548

I want to go through issue ionic-team/ionic-framework#5651 as part of this issue.

[briandennis]

Support for the syntax @brandyscarney described has been added with ionic-team/ionic-framework@d5da8ab

[brandyscarney]

Yay! Now we just need to update all of the Sass files (nbd). 😄

http://ionic-site-staging.herokuapp.com/docs/v2/nightly/api/components/tabs/Tabs/#sass-variables

Great job Brian! 🎉

[mhartington]

[brandyscarney]

🎉 🎉 🎉

[briandennis]

Keeping the issue open until all of the variables have been converted over