Add a docs watcher for the dev server - #5495
Conversation
|
@knolleary for your consideration when you're back |
✅ Deploy Preview for flowforge-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
I tried this locally a few times without success - I get out of memory errors every time I change any docs.
|
|
The memory required by nuxt to rebuild the site when docs update is completely unworkable. It should not require GBs of memory to turn some markdown into html. The only solution I can think of would be to make the script smarter - only copy files that have changed. That is its own resource intensive operation, but, to be frank, I'd rather wait a few seconds for the rebuild to happen, then have to restart the whole stack every time. |
copyDocsDir walks a whole tree at once, which is all a build needs. A dev-server edit needs the opposite: one file. Split the per-file copy out of the walk so both go through the same code, and expose it as syncDocsPath, which also removes a page whose source has gone. Checked against the real docs tree that a full sync still produces byte-identical output, since the CI documentation check and the Netlify deploy both run through it.
nuxt/modules/docs-source.ts syncs once inside Nuxt's setup(), so a docs edit never re-syncs and the dev server has to be restarted to see it. Watch the resolved docs instead and sync each change on its own. chokidar rather than nodemon: nodemon restarts a command, so the only thing it can run is the whole sync, which deletes and recreates all 130-odd pages on every save. The dev server runs out of heap re-indexing that. chokidar also polls when CHOKIDAR_USEPOLLING is set, which is how every other watcher in this repo reaches host edits from the dev container.
b1e8f9b to
56537f2
Compare
dev:nuxt is what both files point docs authors at, and it is the one dev command that does not start dev:docs, so an edit there still needs a restart.
|
@knolleary I did another run on it, can you check it again? |
|
Looks much better - thanks @dimitrieh |
2 participants
Description
Editing a product doc currently means restarting the dev server, because
docs-source.tssyncs once inside Nuxt's
setup()and never again. This watches the resolved docs and syncseach change.
The first version of this ran the existing whole-tree sync on every save. That deletes and
recreates all 130-odd pages, and the dev server ran out of heap re-indexing them, on the
first edit. So the sync gained a single-file path and the watcher uses it: one edit, one
write. A full build still produces byte-identical output, which matters because the CI docs
check and the Netlify deploy both run through it.
chokidar rather than nodemon, because nodemon can only re-run a command and cannot say which
file changed.
Verified against a real flowfuse checkout: 30 consecutive edits with the dev server alive and
its memory flat, plus new page, delete, rename, README and image cases, and the clone case
exiting instead of watching nothing.
Related Issue(s)
Closes #5432
Checklist