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

feat: legacy html generator #55

Merged
merged 18 commits into from
Aug 27, 2024
Merged

feat: legacy html generator #55

merged 18 commits into from
Aug 27, 2024

Conversation

ovflowd
Copy link
Member

@ovflowd ovflowd commented Aug 5, 2024

Description

This PR introduces the Legacy HTML generator, which aims to generate an almost 1:1 replica of the existing https://nodejs.org/api/ documentation.

This PR introduces the fully-fledged legacy-HTML generator, with all the related utilities and tools to make complete API docs in HTML.

Diversions from the original version:

  • Some of the outputted HTML in the "view source" might be different
  • The styles got a bit updated due to CSS conflicts with Shiki (Syntax Highlighter)
  • A new syntax highlighter is being used (same as the Node.js Website), meaning token colors will differ.
  • Sidebar Navigation is generated on-demand instead of relying on nodejs/node/doc/api/index.md
    • This means some of the entries are a bit different, although I believe they are fine.
  • Copy button for CodeBoxes on the top instead of the bottom.
  • Stability Index position is slightly below now (below the History Table and Source Link)

Things to be done:

None. We're feature complete!

Future generators

  • json generator, being able to generate .json files for API docs
  • react generator, the redesign of API docs generator.

Validation

Clone, run npm install, then run the command against Node.js API docs, for example:

npx api-docs-tooling -i "/path/to/node/doc/api/*.md" -t legacy-html -o /tmp/out

You can just open the desired files on your browser.

Preview

This is deployed temporarily on Netlify (not auto deployed on commits, I'm manually deploying it): https://node-api-docs-legacy-preview.netlify.app/

Related Issues

Closes #15

@ovflowd ovflowd requested a review from a team as a code owner August 5, 2024 03:20
jsconfig.json Outdated Show resolved Hide resolved
eslint.config.mjs Outdated Show resolved Hide resolved
@ovflowd

This comment was marked as resolved.

@targos

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@targos

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@targos

This comment was marked as resolved.

@ovflowd
Copy link
Member Author

ovflowd commented Aug 5, 2024

To be honest, the nodejs.org search box already includes all the API data

It only works for the latest LTS version (AFAIK)

Correct, it indexes the LTS version. That's a good point. @micheleriva, what are the alternatives here? Can we make it for API doc generation so the whole database can be built locally based on metadata we ingest? i.e., is it a static database stored in a static file and loaded by the Orama client during bootstrap (client side)

eslint.config.mjs Outdated Show resolved Hide resolved
eslint.config.mjs Outdated Show resolved Hide resolved
src/constants.mjs Outdated Show resolved Hide resolved
src/constants.mjs Outdated Show resolved Hide resolved
src/generators/legacy-html/utils/buildContent.mjs Outdated Show resolved Hide resolved
src/utils/generators.mjs Outdated Show resolved Hide resolved
Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

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

lgtm

@ovflowd

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@micheleriva
Copy link

Correct, it indexes the LTS version. That's a good point. @micheleriva, what are the alternatives here? Can we make it for API doc generation so the whole database can be built locally based on metadata we ingest? i.e., is it a static database stored in a static file and loaded by the Orama client during bootstrap (client side)

@ovflowd sorry for my late reply. Yes, we can definitely do this. Let me just point out that the search results may slightly differ from Orama Cloud (more performant, more accurate results) and Orama OSS. I hope that's not a dealbreaker.

@ovflowd
Copy link
Member Author

ovflowd commented Aug 6, 2024

Correct, it indexes the LTS version. That's a good point. @micheleriva, what are the alternatives here? Can we make it for API doc generation so the whole database can be built locally based on metadata we ingest? i.e., is it a static database stored in a static file and loaded by the Orama client during bootstrap (client side)

@ovflowd sorry for my late reply. Yes, we can definitely do this. Let me just point out that the search results may slightly differ from Orama Cloud (more performant, more accurate results) and Orama OSS. I hope that's not a dealbreaker.

I think that's a fair trade-off, at least within directly the Node.js API docs pages. Are there docs out there on how we can use this?

src/metadata.mjs Outdated Show resolved Hide resolved
@micheleriva
Copy link

I think that's a fair trade-off, at least within directly the Node.js API docs pages. Are there docs out there on how we can use this?

We have our docs at https://docs.orama.com/open-source, and you would probably need to use that plugin: https://docs.orama.com/open-source/plugins/plugin-data-persistence.

We can give you support probably starting next week or so to write down a reference architecture/implementation 🙏

JakobJingleheimer

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@ovflowd

This comment was marked as outdated.

ovflowd added a commit that referenced this pull request Aug 8, 2024
* refactor: applied bug fixes and code refactor from #55

* fix: original type
@ovflowd ovflowd force-pushed the feat/legacy-html-generator branch from 508950d to f3bc34e Compare August 8, 2024 09:20
@ovflowd

This comment was marked as resolved.

@ovflowd ovflowd force-pushed the feat/legacy-html-generator branch from f3bc34e to 147a349 Compare August 10, 2024 11:58
@ovflowd

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@ovflowd ovflowd force-pushed the feat/legacy-html-generator branch from f9f7b64 to 6f57517 Compare August 25, 2024 13:10
@targos

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@targos

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@ovflowd

This comment was marked as resolved.

@targos

This comment was marked as resolved.

@ovflowd
Copy link
Member Author

ovflowd commented Aug 26, 2024

I may be wrong, but I think introduced_in is like source_link and type, a special metadata that has nothing to do with API updates like the other ones in your screenshot. It is only used once per markdown file, near the top.

@targos Ive updated the code so that the metadata generation is like on the current API docs. I will update the tests of this PR later.

@ovflowd
Copy link
Member Author

ovflowd commented Aug 27, 2024

@nodejs/web-infra @canerakdas one last code review? 🙏

Also, @targos let me know if you find any other inconsistency 🙏

@ovflowd
Copy link
Member Author

ovflowd commented Aug 27, 2024

FYI I'merging this for the time being, to unblock @flakey5; Happy to iterate on following PRs. @AugustinMauroy I would love if you could help with some extra tests now that the logic is full I believe you have more material to test! 😃

If you want you can also use the experimental snapshot feature for snapshot tests of html output based on mock markdown sources that mock numerous different pieces of our metadata and content (code blocks, switchable code blocks, all sort of yaml metadata etc)

I think that working on said tests would be awesome for you to get familiar with the nitty gritty of our API docs stuff ;D

@ovflowd ovflowd merged commit 1942f98 into main Aug 27, 2024
7 checks passed
@ovflowd
Copy link
Member Author

ovflowd commented Aug 27, 2024

@targos let me know if perchance I also missed anything. @flakey5 is working on the json generator (legacy-json and legacy-json-all) to generate matching json output for the current api docs :)

After that I believe we would be able to start the process of replacing the current tooling with this one on nodejs/node

@ovflowd ovflowd deleted the feat/legacy-html-generator branch August 28, 2024 23:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add mdx-html generator (Legacy Generator)