Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CSS Variables are not documented using docs-readme output target #3034

Closed
danschultz opened this issue Aug 27, 2021 · 8 comments
Closed

CSS Variables are not documented using docs-readme output target #3034

danschultz opened this issue Aug 27, 2021 · 8 comments
Labels
Resolution: Refine This PR is marked for Jira refinement. We're not working on it - we're talking it through.

Comments

@danschultz
Copy link

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:

@ionitron-bot ionitron-bot bot added the triage label Aug 27, 2021
@dmartinjs
Copy link

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
Copy link
Contributor

👋

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!

@rwaskiewicz rwaskiewicz added Awaiting Reply This PR or Issue needs a reply from the original reporter. Integration: Auto documentation labels Aug 31, 2021
@danschultz
Copy link
Author

danschultz commented Sep 20, 2021

@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.

@ionitron-bot ionitron-bot bot added Reply Received and removed Awaiting Reply This PR or Issue needs a reply from the original reporter. labels Sep 20, 2021
@dmartinjs
Copy link

@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
Copy link
Author

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
Copy link
Contributor

rwaskiewicz commented Sep 21, 2021

👋 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

@rwaskiewicz rwaskiewicz added the Resolution: Refine This PR is marked for Jira refinement. We're not working on it - we're talking it through. label Sep 21, 2021
@danschultz
Copy link
Author

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

@rwaskiewicz
Copy link
Contributor

👋 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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Resolution: Refine This PR is marked for Jira refinement. We're not working on it - we're talking it through.
Projects
None yet
Development

No branches or pull requests

3 participants