Rebuild docs when snippet changes.

mbrandonw commented 1 year ago

Description

When previewing docs with the swift package preview-documentation I have found that changes made to snippet files (in the Snippets root directory) do not trigger a rebuild of docs. This makes it hard to iterate on documentation that uses snippets.

Further, I found found that snippets in the generated docs will update unless the preview server is stopped and restarted. For example, I can perform the following steps:

Start the preview server for my docs (i.e. swift package preview-documentation)
Open docs and confirm everything is running correctly
Make a change to a snippet file in the Snippets directory
Make a change to a documentation file
Confirm that the docs did rebuild in Terminal
Open the docs and see the old version of the snippet.

The only way to see the newest version of the snippet is to stop the preview server and start it again.

Checklist

[X] If possible, I've reproduced the issue using the main branch of this package.
[X] This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

I would hope that any changes to a snippet file or the main docs would rebuild all of the docs with the freshest version of all snippets.

Actual behavior

Snippets are not re-generated unless I stop the preview server and restart it.

Steps To Reproduce

No response

Swift-DocC Version Information

1.2.0

Swift Compiler Version Information

swift-driver version: 1.75.2 Apple Swift version 5.8.1 (swiftlang-5.8.0.124.5 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0

ethan-kusters commented 1 year ago

Keeping this issue as snippet-focused makes sense to me but note that this problem affects any source code change. The live update feature currently only supports changes in markdown files – so any changes in a project's source code will not be reflected without a complete rebuild.

natikgadzhi commented 1 year ago

@ethan-kusters, it looks like the preview action in docc monitors the documentation bundle, but not other directories in the source tree.

A naive approach could be to set the project root (containing the docs bundle) as monitoring target, so any file change would trigger a rebuild?

The problem with that is that DirectoryMonitor will re-run convertAction on every change, i.e. rebuild the whole thing from scratch (unless docc has caching internally that I don't know about yet).

Rebuilding docs on code change would also require building the code (at least obtaining a fresh symbols.json). At least that part is already incremental.

Sounds like a topic for another RFC to align on possible approaches with sane performance costs?

Joannis commented 3 months ago

Is this issue still being considered?

swiftlang / swift-docc-plugin