Introducing Documentation Generation for Swift Packages

[taylorswift]

@SDGGiesbrecht

0. You didn’t actually ask this, but if you just want to use the documentation generator this thread is about and not the other utilities (which is where all the errors are occurring), you can just run $ workspace document or $ workspace validate documentation instead of the general workspace validate (which is what the provided script does).

It seems to be asking for a localization which I don’t know how to provide

png$ ~/tools/sources/Workspace/.build/release/workspace document

Generating documentation... (§1)

Loading “Workspace.swift”...
There are no localizations specified. (documentation.localizations)

✗ Failed to generate documentation. (See Ctrl + F “§1”)

“PNG” fails validation.

@SDGGiesbrecht

The unicode rule discourages ASCII workarounds in favour of real Unicode. ≥ is a valid operator in Swift. Workspace tries to recognize operator aliases like this one and not complain when the operator is just used in order to create a better alias for it. (The linked function does not trigger a violation.)

Are you sure this is a good default setting? Very very few mature Swift projects allow let alone encourage unicode operators.

@SDGGiesbrecht

This is also the unicode rule at work. It allows syntactic use of the ASCII quote in Swift source, but prevents them in strings, documentation and comments. Workspace does not check comments to see if they might be commented source. I’m not sure how it would be possible to reliably tell the difference.

Again, I don’t know how much value this provides. Straight quotes in body copy indicate “computer strings” as opposed to English words or phrases, which take curly quotes.

Some of these substitutions also seem just wrong:

Line 73
U+2026 may be lost in normalization; use “...” instead. (compatibilityCharacters)
### *...safe*
### *...safe*

... and … should never be considered interchangeable, this comes straight from Butterick’s Practical Typography. Very modern fonts are capable of spacing the three-periods version correctly via a ligature but few text rendering engines support this.

@SDGGiesbrecht

It may just be fetching and building SwiftLint if Workspace cannot locate it already on the system (such as within Xcode’s sandbox. Though it gets cached, it can take a while the first time (maybe 5 mins), and depending on the number of cores and the environment, Workspace might not be getting the output until swift run completely finishes.

Right now this is failing with

$ swiftlint lint --strict --reporter emoji
Fatal error: POSIX command failed with error: 13: file Foundation/Process.swift, line 543
Illegal instruction (core dumped)

@SDGGiesbrecht

Is kelvin13/png the project that encountered this? If so, I can troubleshoot it in more depth myself.

Yes