search

nicklockwood / Euclid

A Swift library for creating and manipulating 3D geometry
MIT License
639 stars 53 forks source link

docbuild update #81

Closed heckj closed 2 years ago

heckj commented 2 years ago

This should render the docs correctly with export TOOLCHAIN=swift - I verified it locally with the latest swift 5.6 toolchain installed.

There's something slightly awry with the package plugin and the nightly toolchain, so I shifted away from it - that being the weak point. At one point I got an error in the dynamic package tooling compilation stage about the plugin not conforming to the package manager's command plugin protocol, but I'm not getting that result consistently, which is really weird.

In any case, this doesn't use the new package manager plugin mechanisms, but otherwise works cleanly - so it should smooth the path to generating docs.

nicklockwood commented 2 years ago

Amazing, thanks!

nicklockwood commented 2 years ago

@heckj Should I add all_identifiers.txt and all_symbols.txt to .gitignore? They are recreated each time I run the build script.

heckj commented 2 years ago

Yeah, I do - we can even just pull that from the script. I used it to get a dumped list of all the symbols to make it easier to organize things and see what was there.

On Feb 11, 2022, at 2:11 PM, Nick Lockwood @.***> wrote:

@heckj https://github.com/heckj Should I add all_identifiers.txt and all_symbols.txt to .gitignore? They are recreated each time I run the build script.

— Reply to this email directly, view it on GitHub https://github.com/nicklockwood/Euclid/pull/81#issuecomment-1036674907, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAKS7DRLKEXDDHYJOWE4ILU2WCQNANCNFSM5OFH33GQ. You are receiving this because you were mentioned.

nicklockwood commented 2 years ago

@heckj the generated docs folder has a blank index.html file, and then the actual docs are located at the subpath /documentation/euclid, which is a bit awkward for the github site since it means I have to link directly to the subpath, and anyone who comes to the site directly won't be able to find the docs. Is there any way to fix that?

heckj commented 2 years ago

I suspect there is, but honestly not that I've yet found. And yeah, it's darned awkward!

There's experimental mention of a optional header HTML file, but I haven't sorted if that's a path to what we'd like (header for the set, vs. header for something else) - so right now I'm just linking directly to that "lower" directory structure from the top level of repo, annoying as that is.

nicklockwood commented 2 years ago

@heckj thanks! One more thing - the md files in the Euclid.docc/Extensions directory look like they were generated automatically, but I'm not clear how. Is there another script or something for updating those?

heckj commented 2 years ago

Nope, I'm sorry. Those were hand authored by yours truly. Although that is what I used the list of symbols that the docbuild.bash script generated. My general process was:

In practice, as you update the API, you'll see new methods appearing beneath the organized sets if they're not in that list of symbols, so it's pretty quickly to identify them and shift them up to where they're relevant, move deprecated methods (if any) to the bottom of each organization section, or create new sections and re-order things if that all changes.

nicklockwood commented 2 years ago

@heckj something I've noticed is that rebuilding the docs is very noisy in terms of diffs because the order of the JSON file contents seems to be randomized. Is there anything we can do about that? It would be great to be able to see what's actually changed in the git history.

heckj commented 2 years ago

I've seen the same thing, and opened https://github.com/nicklockwood/Euclid/pull/85 to at least somewhat help.

The core of DocC embraces the unstructured ordering of dictionaries, which causes most (but not all) of the churn, and adding an environment variable to force a pretty-print mode helps there because it makes it ordered. There's also an upstream PR (https://github.com/apple/swift-docc/pull/78) on DocC which would enable this by default (which feels very much like the right move to me) - the only quibbles holding it up are performance related.