chore: make doc-kit friendly - #999
Conversation
PR SummaryMedium Risk Overview
Documentation is reorganized for general adopters: new guides (writing docs, customization, publishing, troubleshooting, CLI reference), Reviewed by Cursor Bugbot for commit a13933b. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #999 +/- ##
==========================================
- Coverage 89.63% 88.10% -1.54%
==========================================
Files 200 210 +10
Lines 18501 19934 +1433
Branches 1729 1860 +131
==========================================
+ Hits 16584 17562 +978
- Misses 1910 2364 +454
- Partials 7 8 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
| File | Main | PR | Change |
|---|---|---|---|
orama-db.json |
9.03 MB | 9.03 MB | +1.00 B (+0.0%) |
Performance estimate (single CI run)
- Generation time: 5.1% slower (8.08 s → 8.49 s)
- Peak memory: 12.2% lower (1.91 GB → 1.68 GB)
web Generator
Output size: 1 file changed · net -112.00 B
File size details
| File | Main | PR | Change |
|---|---|---|---|
all.html |
31.41 MB | 31.41 MB | -112.00 B (-0.0%) |
Performance estimate (single CI run)
- Generation time: 1.3% slower (83.89 s → 84.98 s)
- Peak memory: 6.1% higher (4.65 GB → 4.93 GB)
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a13933b. Configure here.
There was a problem hiding this comment.
What exactly an install command does for us?
There was a problem hiding this comment.
I don't think we should have an install command. We should defer to package managers to install packages. Not doc-kit, I don't think any other tool does something like that.
There was a problem hiding this comment.
We spoke in the meeting about the concern of users not being able to remember the names of packages (e.g. @nodejs/doc-kit-generator-react), so I figured a shorthand to install them would make sense
There was a problem hiding this comment.
Are we making some sort of CRA but for doc-kit?
There was a problem hiding this comment.
Yes and no. Yes, it's a CRA, but it adapts to already set up documentation, rather than creating a whole new app with a package.json, etc
ovflowd
left a comment
ovflowd
left a comment
There was a problem hiding this comment.
Actually, I feel this requires more thought/reviews before proceeding with this. I'm unsure how I feel with this. Could you create an issue so we can chat about the api design regarding a "create react app" sort of wrapper for doc-kit?
|
@ovflowd done, but what are your concerns? |
If doing this is the right path. Even React abandoned housing something like CRA. I get that some tools, such as Next.js themselves have also a way to bootstrap a Next.js app, but I'd argue this shouldn't be part of doc-kit itself, nor we should rewrite our commands to acommodate that. It should probably be its own package, within the monorepo (maybe?) Plus the PR is introducing 3 different commands:
|
Serve does not than just serve, it also watches for changes and reports on errors, so users can build + watch their docs, such as |
I'm thinking about users who know the name of the generator they want, but not which package it is in. It's fairly simple for us to resolve that by adding a basic downloading command. Bootstrap does this, fwiw. |
Again, unsure if this is needed/should be owned by us. Would appreciate consensus first 🙈 |
That's fair, but can't they just go to the website, open searchbar and do that? Why a whole command for that? |
|
the entirety of a getting started experience currently fits "above the fold" within https://doc-kit.nodejs.org/getting-started.html - you can go from empty project to something rendered in seconds. i agree that serve/watch might be the most useful. installation i usually prefer to be ergonomic to package managers. users wants to install things in this security environment my two cents. i probably didnt think through it as deeply as i should have when you asked in Slack Aviv. this body of work is less important to me than making the defaults generic. sample size is small. getting more feedback is a good idea |
|
If I broke out the commands into idiomatic PRs, and the docs into this PR, would that be able to land the better docs before render? |
Ahead of RenderATL, this PR makes doc-kit user friendly with:
doc-kit servedoc-kit bootstrapdoc-kit installcc @ovflowd @bmuenzenmeyer I'll open a PR when this lands to remove the Node.js-isms, figured this one was. big enough