fix(docs): parse css variables docs (#2273)

src/compiler/config/validate-config.ts

@@ -83,6 +83,7 @@ export function validateConfig(config: d.Config): { config: d.Config, diagnostic
   setBooleanConfig(config, 'minifyJs', null, !config.devMode);
 
   setBooleanConfig(config, 'buildEs5', 'es5', !config.devMode);
+  setBooleanConfig(config, 'buildDocs', 'docs', !config.devMode);
   setBooleanConfig(config, 'buildDist', 'esm', !config.devMode || config.buildEs5);
   setBooleanConfig(config, 'profile', 'profile', config.devMode);
 

src/compiler/output-targets/index.ts

@@ -19,13 +19,14 @@ export async function generateOutputTargets(config: d.Config, compilerCtx: d.Com
     outputCollections(config, compilerCtx, buildCtx),
     outputModulesApp(config, compilerCtx, buildCtx),
     outputHydrate(config, compilerCtx, buildCtx),
-    outputDocs(config, compilerCtx, buildCtx),
     outputAngular(config, compilerCtx, buildCtx),
     outputLazyLoader(config, compilerCtx),
 
     buildCtx.stylesPromise
   ]);
 
+  await outputDocs(config, compilerCtx, buildCtx),
+
   // must run after all the other outputs
   // since it validates files were created
   await outputTypes(config, compilerCtx, buildCtx);

src/compiler/output-targets/output-docs.ts

@@ -9,6 +9,9 @@ import { outputCustom } from './output-custom';
 
 
 export const outputDocs = async (config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) => {
+  if (!config.buildDocs) {
+    return;
+  }
   const docsOutputTargets = config.outputTargets.filter(o => (
     isOutputTargetCustom(o) ||
     isOutputTargetDocsReadme(o) ||

src/compiler/style/css-to-esm.ts

@@ -7,6 +7,7 @@ import { serializeImportPath } from '../transformers/stencil-import-path';
 import { stripCssComments } from './style-utils';
 import MagicString from 'magic-string';
 import path from 'path';
+import { parseStyleDocs } from '../docs/style-docs';
 
 
 export const transformCssToEsm = async (input: d.TransformCssToEsmInput) => {
@@ -42,8 +43,13 @@ const transformCssToEsmModule = (input: d.TransformCssToEsmInput) => {
     diagnostics: [],
     imports: [],
     defaultVarName: createCssVarName(input.file, input.mode),
+    styleDocs: []
   };
 
+  if (input.docs) {
+    parseStyleDocs(results.styleDocs, input.input);
+  }
+
   try {
     const varNames = new Set([results.defaultVarName]);
 

src/compiler_next/bundle/ext-transforms-plugin.ts

@@ -4,6 +4,7 @@ import { hasError, normalizeFsPath } from '@utils';
 import { parseImportPath } from '../../compiler/transformers/stencil-import-path';
 import { Plugin } from 'rollup';
 import { runPluginTransformsEsmImports } from '../../compiler/plugin/plugin';
+import { isOutputTargetDistCollection } from '../../compiler/output-targets/output-utils';
 
 
 export const extTransformsPlugin = (config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx, bundleOpts: BundleOptions): Plugin => {
@@ -19,14 +20,13 @@ export const extTransformsPlugin = (config: d.Config, compilerCtx: d.CompilerCtx
       if (data != null) {
         const filePath = normalizeFsPath(id);
         const code = await compilerCtx.fs.readFile(filePath);
+        const cmp = buildCtx.components.find(c => c.tagName === data.tag);
+        const moduleFile = cmp && compilerCtx.moduleMap.get(cmp.sourceFilePath);
         const pluginTransforms = await runPluginTransformsEsmImports(config, compilerCtx, code, filePath);
-
-        const modules = Array.from(compilerCtx.moduleMap.values());
-        const moduleFile = modules.find(m => m.cmps.some(c => c.tagName === data.tag));
         const commentOriginalSelector = (bundleOpts.platform === 'hydrate') && (data.encapsulation === 'shadow');
 
         if (moduleFile) {
-          const collectionDirs = (config.outputTargets as d.OutputTargetDist[]).filter(o => o.collectionDir);
+          const collectionDirs = config.outputTargets.filter(isOutputTargetDistCollection);
 
           const relPath = config.sys.path.relative(config.srcDir, pluginTransforms.id);
 
@@ -46,8 +46,14 @@ export const extTransformsPlugin = (config: d.Config, compilerCtx: d.CompilerCtx
           sourceMap: config.sourceMap,
           minify: config.minifyCss,
           autoprefixer: config.autoprefixCss,
+          docs: config.buildDocs
         });
 
+        // Set style docs
+        if (cmp) {
+          cmp.styleDocs = cssTransformResults.styleDocs;
+        }
+
         // Track dependencies
         pluginTransforms.dependencies.forEach(dep => {
           this.addWatchFile(dep);

src/compiler_next/config/validate-config.ts

@@ -55,6 +55,7 @@ export const validateConfig = (userConfig?: Config) => {
   setBooleanConfig(config, 'minifyCss', null, !config.devMode);
   setBooleanConfig(config, 'minifyJs', null, !config.devMode);
   setBooleanConfig(config, 'buildEs5', 'es5', !config.devMode);
+  setBooleanConfig(config, 'buildDocs', 'docs', !config.devMode);
   setBooleanConfig(config, 'writeLog', 'log', false);
   setBooleanConfig(config, 'buildAppCore', null, true);
   setBooleanConfig(config, 'autoprefixCss', null, config.buildEs5);

src/compiler_next/output-targets/docs/output-docs.ts

@@ -9,6 +9,9 @@ import { outputCustom } from '../../../compiler/output-targets/output-custom';
 
 
 export async function outputDocs(config: d.Config, compilerCtx: d.CompilerCtx, buildCtx: d.BuildCtx) {
+  if (!config.buildDocs) {
+    return;
+  }
   const docsOutputTargets = config.outputTargets.filter(o => (
     isOutputTargetCustom(o) ||
     isOutputTargetDocsReadme(o) ||

src/compiler_next/output-targets/index.ts

@@ -3,7 +3,7 @@ import { outputAngular } from '../../compiler/output-targets/output-angular';
 import { outputCopy } from './copy/output-copy';
 import { outputCustomElements } from './dist-custom-elements';
 import { outputCustomElementsBundle } from './dist-custom-elements-bundle';
-import { outputDocs } from '../../compiler/output-targets/output-docs';
+import { outputDocs } from './docs/output-docs';
 import { outputHydrateScript } from './dist-hydrate-script';
 import { outputLazy } from './dist-lazy/lazy-output';
 import { outputLazyLoader } from '../../compiler/output-targets/output-lazy-loader';
@@ -30,14 +30,14 @@ export const generateOutputTargets = async (config: d.Config, compilerCtx: d.Com
     outputCollection(config, compilerCtx, buildCtx, changedModuleFiles),
     outputCustomElements(config, compilerCtx, buildCtx, changedModuleFiles),
     outputCustomElementsBundle(config, compilerCtx, buildCtx),
-    outputDocs(config, compilerCtx, buildCtx),
     outputHydrateScript(config, compilerCtx, buildCtx),
     outputLazyLoader(config, compilerCtx),
     outputApp(config, compilerCtx, buildCtx),
   ]);
 
   // must run after all the other outputs
   // since it validates files were created
+  await outputDocs(config, compilerCtx, buildCtx);
   await outputTypes(config, compilerCtx, buildCtx);
 
   timeSpan.finish('generate outputs finished');

src/declarations/stencil-private.ts

@@ -26,6 +26,7 @@ import {
   PrerenderRequest,
   PrerenderResults,
   StencilSystem,
+  StyleDoc,
 } from './stencil-public-compiler';
 
 import {
@@ -2249,6 +2250,7 @@ export interface TransformCssToEsmInput {
   commentOriginalSelector?: boolean;
   sourceMap?: boolean;
   minify?: boolean;
+  docs?: boolean;
   autoprefixer?: any;
 }
 
@@ -2258,6 +2260,7 @@ export interface TransformCssToEsmOutput {
   map: any;
   diagnostics: Diagnostic[];
   defaultVarName: string;
+  styleDocs: StyleDoc[];
   imports: { varName: string; importPath: string;}[];
 }
 

src/declarations/stencil-public-compiler.ts

@@ -286,6 +286,7 @@ export interface ConfigExtras {
 
 export interface Config extends StencilConfig {
   buildAppCore?: boolean;
+  buildDocs?: boolean;
   configPath?: string;
   cwd?: string;
   writeLog?: boolean;