Hi all,
I have two questions:
Firstly, Is there any place that shows how to config a docc package to automatically generate the documents to a folder? Is adding a build script the right way to achieve this goal?
Secondly, I want to publish the document to a folder like docs automatically and then use a static host like GitHub Pages. Every time I generate a document it regenerates all the files and I should commit them. Is there any way to prevent this?
There's multiple ways to achieve this, but likely the most straightforward is adding a dependency to the swift-docc-plugin and using a script to invoke the plugin to do the lifting. The other options (using DocC directly) require more setup and interaction with the modules. If you want to borrow an example script along those lines, feel free to grab and re-use https://github.com/heckj/CRDT/blob/main/docbuild.bash. There's extra bits in there, and you really need only line 19 and 44 through 53 for the work. It might help explain things to you - I've been copy-pasting it between projects and slowly evolving it as DocC and the plugin have evolved.
For the dependency, if your swift project supports swift earlier than 5.5, lots of folks are adding it with a "if (swift > 5.5)" predicate in their Package.swift file, which works reasonably well to maintain backward compatibility, but I'd recommend increasing to require at least swift 5.6 support and just adding the dependency directly. You can see an example of such in that same repo - line 21 of Package.swift.
The addition of export DOCC_JSON_PRETTYPRINT=YES into the build script minimizes the regeneration, but the short answer is - if you want it hosted on github pages, then yeah - you'll need to commit on each iteration. There are still some places where a unchanged project will generate different JSON output with DocC, so there's no brilliant way to make it explicitly deterministic right now. But the commit part is more specific to how Github hosts its pages - so if you're shuttling content of to an internal service or something, a commit might not be needed. Github requires the content to be existing in the repo within an explicit commit, for it's publishing mechanism.
I don't have a quick-and-easy replica script for this, but I suspect there might be some github actions that do this last bit of work pretty much for you. I haven't looked recently though.
The SwiftCrossUI repository on GitHub is set up in a way that is similar to what you want. You can take a look to see how I did it. On a high level I just added the docc plugin to the package and then created a GitHub Actions workflow which builds the docs and commits them to the gh-pages branch (which was created as an orphan branch). GitHub pages was configured to host the gh-pages branch.
Hope this helps :)
Thanks for your answer. I'll give it a try it's enough for me.