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.

Sign up for GitHub

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

Jump to bottom

doc,tools: properly syntax highlight API ref docs #33442

Closed
wants to merge 5 commits into from
Closed

doc,tools: properly syntax highlight API ref docs #33442

wants to merge 5 commits into from

Conversation

DerekNonGeneric
Copy link
Contributor

@DerekNonGeneric DerekNonGeneric commented May 16, 2020 •
edited
Loading

Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

  • remove SHJS JavaScript code
  • add highlight.js bundle
  • fix script tags to reflect replacement
  • migrate CSS to use highlight.js classes
  • add appropriate documentation
  • ensure api_assets README.md stays interal

Fixes: #33363

Checklist

@nodejs-github-bot nodejs-github-bot added the tools Issues and PRs related to the tools directory. label May 16, 2020
doc,tools: properly syntax highlight API ref docs
0bc8b9a 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: #33363
@DerekNonGeneric
Copy link
Contributor Author

I'm pretty sure this PR is now ready for review. I tried to keep this commit uncontroversial by keeping the preexisting syntax theme intact. A couple of the classes had to be removed due to not having a highlight.js equivalent (at least to my knowledge). Any additional feedback is welcome! :)

/cc @nodejs/documentation @Trott @zeke

Before

before-hljs

After

after-hljs

Trott
Trott approved these changes May 17, 2020
View reviewed changes
Copy link
Member

@Trott Trott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this!

@nodejs/documentation @nodejs/Website

lpinca
lpinca approved these changes May 17, 2020
View reviewed changes
Copy link
Member

@lpinca lpinca left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rubber stamp LGTM

nschonni
nschonni approved these changes May 17, 2020
View reviewed changes
Copy link
Member

@nschonni nschonni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I'd just point out the org site is running https://prismjs.com/ rather than highlight.js, but I think that shouldn't be an issue.

XhmikosR
XhmikosR reviewed May 17, 2020
View reviewed changes
doc/api_assets/sh.css Outdated Show resolved Hide resolved
@DerekNonGeneric
Copy link
Contributor Author

I'd just point out the org site is running https://prismjs.com/ rather than highlight.js

Yup, I noticed that. Just being aware of that is important.

Exhibit A: nodejs/nodejs.org#2923

zeke
zeke approved these changes May 17, 2020
View reviewed changes
Copy link
Contributor

@zeke zeke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! 😎

BridgeAR
BridgeAR approved these changes May 18, 2020
View reviewed changes
Copy link
Member

@BridgeAR BridgeAR left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

@BridgeAR
Copy link
Member

@nodejs/documentation does anyone know if there's a test CI that we could run for this? Otherwise this is probably author-ready?

ryzokuken
ryzokuken approved these changes May 18, 2020
View reviewed changes
Copy link
Contributor

@ryzokuken ryzokuken left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

@richardlau
Copy link
Member

@nodejs/documentation does anyone know if there's a test CI that we could run for this? Otherwise this is probably author-ready?

The build-docs GitHub workflow does upload the docs as a zip file artifact if anyone wants to visually inspect the built results.

@DerekNonGeneric
Copy link
Contributor Author

DerekNonGeneric commented May 18, 2020 •
edited
Loading

I've added six lines of CSS to prevent introducing a subtle visual regression in the highlighted JSDoc.

Original

original-doctag-css

Before Added CSS

before-hljs-doctag-css

After Added CSS

after-hljs-doctag-css

@DerekNonGeneric
Copy link
Contributor Author

Otherwise this is probably author-ready?

+1 to label:"author ready" if the license builder commit (0acdfe2) is looking good.

/cc @MylesBorins

@DerekNonGeneric
Copy link
Contributor Author

DerekNonGeneric commented May 19, 2020 •
edited
Loading

@nodejs/documentation does anyone know if there's a test CI that we could run for this?

To increase confidence that the bundle published is the one intended, we could do a checksum comparison. This would ensure that the bundle in doc/api_assets is the one that gets client-side executed by users' browsers.

BridgeAR pushed a commit to BridgeAR/node that referenced this pull request May 23, 2020
@DerekNonGeneric @BridgeAR
doc,tools: properly syntax highlight API ref docs
dc6c93c 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: nodejs#33363

PR-URL: nodejs#33442
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
@BridgeAR
Copy link
Member

Landed in dc6c93c 🎉

@BridgeAR BridgeAR closed this May 23, 2020
@BethGriggs BethGriggs mentioned this pull request Jun 8, 2020
Closed
codebytere pushed a commit that referenced this pull request Jun 18, 2020
@codebytere
doc,tools: properly syntax highlight API ref docs
c7575ee 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: #33363

PR-URL: #33442
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
codebytere pushed a commit that referenced this pull request Jun 18, 2020
@codebytere
doc,tools: properly syntax highlight API ref docs
af9fb59 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: #33363

PR-URL: #33442
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
@codebytere codebytere mentioned this pull request Jun 28, 2020
Merged
codebytere pushed a commit that referenced this pull request Jun 30, 2020
@codebytere
doc,tools: properly syntax highlight API ref docs
8fc790b 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: #33363

PR-URL: #33442
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
codebytere pushed a commit that referenced this pull request Jul 8, 2020
@codebytere
doc,tools: properly syntax highlight API ref docs
6f8b7a8 
Prior to this commit, all <pre> tags were being
highlighted as JavaScript. This has been corrected
to syntax highlight all languages appearing in the
API reference docs. This was accomplished by using
highlight.js instead of SHJS for the frontend lib.

* remove SHJS JavaScript code
* add highlight.js bundle
* fix script tags to reflect replacement
* migrate CSS to use highlight.js classes
* add appropriate documentation
* ensure api_assets README.md stays interal

Fixes: #33363

PR-URL: #33442
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
@codebytere codebytere mentioned this pull request Jul 13, 2020
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@XhmikosR XhmikosR XhmikosR left review comments

@3imed-jaberi 3imed-jaberi 3imed-jaberi approved these changes

@aymen94 aymen94 aymen94 approved these changes

@ryzokuken ryzokuken ryzokuken approved these changes

@BridgeAR BridgeAR BridgeAR approved these changes

@zlatanvasovic zlatanvasovic zlatanvasovic approved these changes

@willin willin willin approved these changes

@lpinca lpinca lpinca approved these changes

@nschonni nschonni nschonni approved these changes

@Trott Trott Trott approved these changes

@zeke zeke zeke approved these changes

Assignees
No one assigned
Labels
tools Issues and PRs related to the tools directory.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

doc: all <pre> tags are highlighted as JavaScript