Giters

swiftlang / swift-docc-plugin

Swift Package Manager command plugin for Swift-DocC

Home Page:https://swiftpackageindex.com/apple/swift-docc-plugin/1.3.0/documentation/swiftdoccplugin

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Rebuild docs when snippet changes.

mbrandonw opened this issue · comments

commented

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

  • If possible, I've reproduced the issue using the main branch of this package.
  • 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
commented

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.

commented

@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?

commented

Is this issue still being considered?