CSS Variables are not documented using docs-readme output target

[danschultz]

Stencil version:

 @stencil/core@2.7.1

I'm submitting a:

[x] bug report
[ ] feature request
[ ] support request => Please do not submit support requests here, use one of these channels: https://stencil-worldwide.herokuapp.com/ or https://forum.ionicframework.com/

Current behavior:

I'm using the docs-readme output target. Starting with Stencil v2.7.0, CSS variables are no longer being documented in the generated readme.md files.

Expected behavior:

CSS variables that have documentation should be documented in the generated readme.md files.

Steps to reproduce:

Document a CSS variable like this:

:host {
  /**
   * @prop --my-background: Some documentation.
   */
  --my-background: red;
}

Related code:

// insert any relevant code here

Other information:

[dmartinjs]

I just tested it and it works on my side with Stencil 2.7.1

Did you run npm run build or a command containing --docs ?
because the readme output alone isn't generating readme files.

Example on my side:

packages.json

"scripts": {
    "build": "stencil build --docs",
    
  },
``` 

[rwaskiewicz]

👋

Hey there! I tried to reproduce this locally with the following build command:

"build": "stencil build --docs"

and was unable to reproduce this. Can you please push a minimal reproduction up to GitHub for us to investigate further? That allows the team to pull down an example that has confirmed to have the issue present and will allow us to triage more quickly. Thanks!

[danschultz]

@dmartinjs + @rwaskiewicz apologies for the late reply. I have a repro case in https://github.com/Vertexvis/vertex-web-sdk.

To repro, clone the repo and update the version of Stencil (docs are working prior to update). After running a build and doing a diff of the changed files, you'll see that the CSS Custom Properties sections in each of the component readme's are now gone.

$ git clone https://github.com/Vertexvis/vertex-web-sdk.git
$ cd vertex-web-sdk
$ yarn install
$ cd packages/viewer
$ yarn add --dev @stencil/core
$ yarn build
$ git diff

I also tried with a new Stencil project and was not able to repro. Appears there might be something specific with this project that's causing CSS to not be documented.

[dmartinjs]

@danbucholtz I had the error in the past few weeks, I found that they was an error in one of my declaration in a CSS file how caused deletion of all the declarations in readme files.

[danschultz]

I did a little bit more digging. Since version v2.7.0, running stencil build --docs for some reason is causing Stencil to compile our project twice. After the first build runs, the readme's contain the correct CSS property documentation. However, after the second build runs, then the documentation is removed. Any ideas what might be causing Stencil to run a build twice?

$ stencil build --docs
[33:52.5]  @stencil/core
[33:52.9]  v2.7.0 🌟
[34:00.7]  build, viewer, prod mode, started ...
[34:00.7]  transpile started ...
[34:09.5]  transpile finished in 8.84 s
[34:09.5]  copy started ...
[34:09.5]  generate lazy started ...
[34:09.8]  copy finished (0 files) in 240 ms
[34:19.7]  generate lazy finished in 10.14 s
[34:19.7]  generating react-library started ...
[34:19.7]  generate react-library finished in 5 ms

[ WARN  ]  Bundling Warning EVAL
           Use of eval is strongly discouraged, as it poses security risks and may cause issues with minification

[34:19.8]  build finished in 19.14 s

[34:23.8]  build, viewer, prod mode, started ...
[34:23.8]  transpile started ...
[34:32.7]  transpile finished in 8.92 s
[34:32.7]  copy started ...
[34:32.7]  generate lazy started ...
[34:33.2]  copy finished (0 files) in 484 ms
[34:35.2]  generate lazy finished in 2.47 s
[34:35.2]  generating react-library started ...
[34:35.2]  generate react-library finished in 2 ms

[ WARN  ]  Bundling Warning EVAL
           Use of eval is strongly discouraged, as it poses security risks and may cause issues with minification

[34:35.3]  build finished in 11.50 s

I've pushed up a branch with here that simplifies the CSS. If you run yarn build in the ./packages/viewer directory, it should document a CSS property for the scene-tree component.

[rwaskiewicz]

👋 I'm going to mark this to be ingested into our backlog to take a closer look. There's something afoot here, but I'm not sure what just yet. The double build seems to be at the root of things, but I'm not sure why that's running 2x

[danschultz]

Tested this again with v2.12.1 and am unable to repro.

[rwaskiewicz]

👋 Although we closed this issue out, with the help of the Ionic Framework team, we were able to reproduce this successfully. A fix has been implemented (#3374), and is a part of the v2.16.0 release that has gone out this afternoon. Thanks again for reporting this!