Skip to content

Commit

Permalink
docs(sassdoc): updated sassdoc for new module system
Browse files Browse the repository at this point in the history
  • Loading branch information
@mlaursen
mlaursen committed Sep 10, 2021
1 parent ce89374 commit 4746d26
Show file tree
Hide file tree
Showing 5 changed files with 145 additions and 76 deletions.
95 changes: 67 additions & 28 deletions packages/dev-utils/src/sassdoc.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import {
VariableItem,
} from "sassdoc";

import { nonWebpackDist, packagesRoot, src } from "./constants";
import { nonWebpackDist, packagesRoot, src, tempStylesDir } from "./constants";
import {
combineAllFiles,
CompiledExample,
Expand All @@ -24,9 +24,7 @@ import {
FormattedItemLink,
FormattedMixinItem,
FormattedVariableItem,
getColorVariables,
getCompiledValue,
getEverythingScss,
getSassdoc,
isFunctionItem,
isMixinItem,
Expand All @@ -46,7 +44,7 @@ export interface FullItemReferenceLink extends ItemReferenceLink {
}

const NO_COMPILE_TOKEN = "<!-- no-compile -->";
const OVERRIDE_VARIABLES_TOKEN = "// OVERRIDE_VARIABLES";
const OVERRIDE_USE_TOKEN = "// OVERRIDE_USE";
const isCompileable = (value: string): boolean =>
/\$?rmd|if\(/.test(value) && !/^--rmd/.test(value);

Expand Down Expand Up @@ -102,30 +100,45 @@ function getCompiledValueString(value: VariableValue): string {
.substring(prefix.length);
}

function compileExampleCode(code: string, path: string, name: string): string {
let data = code;
let prefix = "";
const i = code.indexOf(OVERRIDE_VARIABLES_TOKEN);
if (i !== -1) {
prefix = code.substring(0, i);
data = code.substring(i + OVERRIDE_VARIABLES_TOKEN.length);
}
interface CompiledExampleOptions {
/**
* A custom `@use` statement.
*/
use: string;
path: string;
name: string;
code: string;
}

// since everything is part of the same stylesheet to prevent the `@import` IO
// slowdown, have to update variables to be `!global` so that they will be
// overridden/found correctly. (mostly typography)
data = `${getColorVariables()}
${prefix.replace(/;$/g, " !global;")}
function compileExampleCode({
use,
name,
path,
code,
}: CompiledExampleOptions): string {
let useModules: string;
if (use) {
useModules = use.replace('"react-md"', '"react-md/dist/scss/everything"');
} else {
useModules = '@use "react-md/dist/scss/everything" as *;\n';
}

${getEverythingScss()}
const data = `${useModules}
${data}`;
${code}
`;

try {
return format(renderSync({ data }).css.toString(), "css");
return format(
renderSync({
data,
includePaths: [tempStylesDir],
}).css.toString(),
"css"
);
} catch (e) {
log.error("Unable to compile an example with the following code:");
log.error(code);
log.error(data);
log.error();
log.error(`path: ${path}`);
log.error(`name: ${name}`);
Expand Down Expand Up @@ -178,6 +191,26 @@ function removeUncompilableCode(code: string): string {

return code;
}

interface FormattedExampleCodeOptions {
use: string;
code: string;
type: ExampleType;
}

function getFormattedExampleCode({
use,
code,
type,
}: FormattedExampleCodeOptions): string {
return format(
`${use || '@use "react-md" as *;\n'}
${code}
`,
getFormatParser(type)
);
}

const isItemRequire = (
item: ItemReference | ItemRequire
): item is ItemRequire => typeof (item as ItemRequire).name === "string";
Expand Down Expand Up @@ -231,18 +264,24 @@ function formatItem(

let examples: CompiledExample[] | undefined;
if (example) {
examples = example.map(({ code, type, description }) => {
const exampleCode = removeUncompilableCode(code);
examples = example.map(({ code: rawCode, type, description }) => {
const parts = removeUncompilableCode(rawCode).split(OVERRIDE_USE_TOKEN);

let use = "";
let code: string;
if (parts.length === 2) {
[use, code] = parts;
} else {
[code] = parts;
}

let compiled: string | undefined;
if (type === "scss" && !description.includes(NO_COMPILE_TOKEN)) {
compiled = compileExampleCode(exampleCode, path, name);
compiled = compileExampleCode({ use, code, name, path });
}

return {
code: format(
exampleCode.replace(OVERRIDE_VARIABLES_TOKEN, ""),
getFormatParser(type)
),
code: getFormattedExampleCode({ use, code, type }),
compiled,
type,
description: formatDescription(description),
Expand Down
2 changes: 2 additions & 0 deletions packages/dev-utils/src/utils/copy/styles.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { join, sep } from "path";

import {
dist,
everythingScss,
nonWebpackDist,
packagesRoot,
projectRoot,
Expand Down Expand Up @@ -89,6 +90,7 @@ function cleanTempStyles(): void {

export async function copyStylesTemp(): Promise<void> {
const files = await glob(PATTERN);
files.push(everythingScss.replace(`${projectRoot}${sep}`, ""));
await Promise.all(
files.map(async (filePath) => {
const contents = getNonTildedContents(filePath);
Expand Down
52 changes: 31 additions & 21 deletions packages/theme/src/_color-a11y.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,13 @@ $rmd-theme-default-contrast-ratio: 3 !default;
/// color variables in react md.
///
/// @example scss - Better Contrast Enabled
/// $rmd-theme-better-contrast-colors: true;
/// $rmd-theme-primary: $rmd-teal-500;
/// $rmd-theme-secondary: $rmd-pink-a-200;
/// // OVERRIDE_VARIABLES
/// @use "@react-md/theme/dist/color-palette" as colors;
/// @use "react-md" as * with (
/// $rmd-theme-better-contrast-colors: true,
/// $rmd-theme-primary: colors.$rmd-teal-500,
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
/// );
/// // OVERRIDE_USE
///
/// // these are the rmd-defaults
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
Expand All @@ -40,10 +43,13 @@ $rmd-theme-default-contrast-ratio: 3 !default;
/// }
///
/// @example scss - Better Contrast Disabled
/// $rmd-theme-better-contrast-colors: false;
/// $rmd-theme-primary: $rmd-teal-500;
/// $rmd-theme-secondary: $rmd-pink-a-200;
/// // OVERRIDE_VARIABLES
/// @use "@react-md/theme/dist/color-palette" as colors;
/// @use "react-md" as * with (
/// $rmd-theme-better-contrast-colors: false,
/// $rmd-theme-primary: colors.$rmd-teal-500,
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
/// );
/// // OVERRIDE_USE
///
/// // these are the rmd-defaults
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
Expand Down Expand Up @@ -251,10 +257,13 @@ $rmd-theme-linear-channel-values: (
/// to the dark color.
///
/// @example scss - Better Contrast Enabled
/// $rmd-theme-better-contrast-colors: true;
/// $rmd-theme-primary: $rmd-teal-500;
/// $rmd-theme-secondary: $rmd-pink-a-200;
/// // OVERRIDE_VARIABLES
/// @use "@react-md/theme/dist/color-palette" as colors;
/// @use "react-md" as * with (
/// $rmd-theme-better-contrast-colors: true,
/// $rmd-theme-primary: colors.$rmd-teal-500,
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
/// );
/// // OVERRIDE_USE
///
/// // these are the rmd-defaults
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
Expand All @@ -264,17 +273,19 @@ $rmd-theme-linear-channel-values: (
/// --p: #{$rmd-theme-primary};
/// --s: #{$rmd-theme-secondary};
///
/// // this should be `#000` once compiled since `#000` has a 5.3 contrast
/// // ratio compared to teal while `#fff` has a 3.6 contrast ratio.
/// // since black has a ~5.3 color ratio as compared to white with ~3.6
/// --op: #{$rmd-theme-on-primary};
/// --os: #{$rmd-theme-on-secondary};
/// }
///
/// @example scss - Better Contrast Disabled
/// $rmd-theme-better-contrast-colors: false;
/// $rmd-theme-primary: $rmd-teal-500;
/// $rmd-theme-secondary: $rmd-pink-a-200;
/// // OVERRIDE_VARIABLES
/// @use "@react-md/theme/dist/color-palette" as colors;
/// @use "react-md" as * with (
/// $rmd-theme-better-contrast-colors: false,
/// $rmd-theme-primary: colors.$rmd-teal-500,
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
/// );
/// // OVERRIDE_USE
///
/// // these are the rmd-defaults
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
Expand All @@ -284,9 +295,8 @@ $rmd-theme-linear-channel-values: (
/// --p: #{$rmd-theme-primary};
/// --s: #{$rmd-theme-secondary};
///
/// // this should be `#fff` once compiled since the light color (`#fff`)
/// // is checked first and meets the minimum contrast ratio requirements
/// // at `3.6`
/// // white has a ~3.6 color ratio so it _is_ contrast compliant with the
/// // minimal contrast ratios even though black would be ~5.6
/// --op: #{$rmd-theme-on-primary};
/// --os: #{$rmd-theme-on-secondary};
/// }
Expand Down
12 changes: 8 additions & 4 deletions packages/theme/src/_mixins.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,10 @@
/// }
///
/// @example scss - Simple Prefers Color Scheme
/// $rmd-theme-dark-class: 'prefers-color-scheme';
/// // OVERRIDE_VARIABLES
/// @use "react-md" as * with (
/// $rmd-theme-dark-class: 'prefers-color-scheme',
/// );
/// // OVERRIDE_USE
///
/// .container {
/// @include rmd-theme-dark-elevation-styles {
Expand Down Expand Up @@ -130,8 +132,10 @@
/// }
///
/// @example scss - CSS Module Prefers Color Scheme Example
/// $rmd-theme-dark-class: 'prefers-color-scheme';
/// // OVERRIDE_VARIABLES
/// @use "react-md" as * with (
/// $rmd-theme-dark-class: 'prefers-color-scheme',
/// );
/// // OVERRIDE_USE
///
/// .container {
/// @include rmd-theme-dark-elevation-styles(true) {
Expand Down
60 changes: 37 additions & 23 deletions packages/typography/src/_variables.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -579,37 +579,38 @@ $rmd-typography-overline-styles: () !default;
/// }
///
/// @example scss - Overriding Typography Values
/// $rmd-typography-styles-headline-1: (
/// font-size: 4rem,
/// line-height: 4rem,
/// margin: 0,
/// @use "react-md" as * with (
/// $rmd-typography-headline-1-styles: (
/// font-size: 4rem,
/// line-height: 4rem,
/// margin: 0,
/// ),
/// $rmd-typography-headline-2-styles: (
/// font-size: 3.5rem,
/// line-height: 3.5rem,
/// margin: 0,
/// ),
/// $rmd-typography-headline-3-styles: (
/// margin: 0,
/// ),
/// $rmd-typography-headline-4-styles: (
/// margin: 0,
/// ),
/// $rmd-typography-headline-5-styles: (
/// margin: 0,
/// ),
/// $rmd-typography-headline-6-styles: (
/// margin: 0,
/// ),
/// );
/// $rmd-typography-styles-headline-2: (
/// font-size: 3.5rem,
/// line-height: 3.5rem,
/// margin: 0,
/// );
/// $rmd-typography-styles-headline-3: (
/// margin: 0,
/// );
/// $rmd-typography-styles-headline-4: (
/// margin: 0,
/// );
/// $rmd-typography-styles-headline-5: (
/// margin: 0,
/// );
/// $rmd-typography-styles-headline-6: (
/// margin: 0,
/// );
/// // OVERRIDE_VARIABLES
/// // OVERRIDE_USE
///
/// @each $style in map-keys($rmd-typography-styles) {
/// .#{$style} {
/// @include rmd-typography($style);
/// }
/// }
///
///
/// @type Map
/// @prop {Map} headline-1 - The styles for a headline-1
/// @prop {Map} headline-2 - The styles for a headline-2
Expand All @@ -624,6 +625,19 @@ $rmd-typography-overline-styles: () !default;
/// @prop {Map} button - The styles for a button
/// @prop {Map} caption - The styles for a caption
/// @prop {Map} overline - The styles for a overline
/// @require $rmd-typography-headline-1-styles
/// @require $rmd-typography-headline-2-styles
/// @require $rmd-typography-headline-3-styles
/// @require $rmd-typography-headline-4-styles
/// @require $rmd-typography-headline-5-styles
/// @require $rmd-typography-headline-6-styles
/// @require $rmd-typography-subtitle-1-styles
/// @require $rmd-typography-subtitle-2-styles
/// @require $rmd-typography-body-1-styles
/// @require $rmd-typography-body-2-styles
/// @require $rmd-typography-button-styles
/// @require $rmd-typography-caption-styles
/// @require $rmd-typography-overline-styles
$rmd-typography-styles: rmd-typography-set-styles(
$rmd-typography-base,
(
Expand Down

0 comments on commit 4746d26

Please sign in to comment.