When I started using swift-docc, I was surprised that it didn’t offer live reloading. It really helps when editing content to see the final result automatically update in the browser. I’ve added this functionality in PR #1417 and am already using it to edit the documentation for my mcp-swift-sdk package.
I’m posting here in addition to my PR because @heckj suggested I do so. Let me know if there’s anything else I can do to get this PR across the finish line.
Thanks @DeSC0M!!
@marcus_ortiz I wanted to check to make sure this wasn't going to run afoul of anything in terms of how the DocC Render app is setup, in terms of including a bit of JS that reloads the page when it gets the relevant server-side event from the CLI that's hosting the preview. I suspect it's fine, but I wanted to double check, and make sure this wasn't running o(or going to run) afoul of the updates that are going into DocC Render lately.
@DeSC0M I'm sure you're already aware, but as you talk about what this enables, I think it's worth being specific that this only reloads on changes to markdown files within the catalog. I've run into multiple folks who expected that documentation changes in source code should be equivalently reflected, and today that isn't the case, including with this PR. When you need to recompile the code to get the symbols to present them - that's not currently included in the reload.
To be clear, I don't think it needs to be to accept this PR, but I wanted to make sure it was clear what this operated on.
I don’t think there would be any major issue from what I’ve briefly seen in the PR since the added JS seems to essentially just reload the page whenever it gets a message to do so.
As a side note, It is worth mentioning that DocC-Render does technically have its own system for “live updating” in response to content changes, but it has only been utilized for IDE environments (VSCode, etc) and requires some additional configuration to communicate between the renderer and the environment where it’s being hosted—it does not do any live updating with docc preview from the command line today (hence this PR).
Just FYI though—I don't think this needs to necessarily be re-implemented using that system since it would likely be more involved, but I thought it would be worth calling out.
Thanks for opening this! One thing that comes to mind is whether we should enable this by default, or whether it should be opt-in, and if default, whether there should be an opt-out. Do you or others have thought about this?
Honestly I think live reload is table stakes for any preview server like this. It certainly is in the web dev world. Is there any reason why someone wouldn’t want this?
Okay, makes sense. Looking at browser support, it seems well supported.