Add support for "warnings as errors"

[Kyle-Ye]

Bug/issue #, if applicable:
Close #363

Summary

Add a new flag "--warnings-as-errors" for "docc convert" Command.

If this flag is set, the engine will treat the warning severity level as an error severity level

Forum discussion post: https://forums.swift.org/t/add-support-for-warnings-as-errors/59832

Dependencies

None

Testing

1. git clone https://github.com/apple/swift-markdown.git
2. Generate swift-markdown's symbol-graph
3. Run

docc convert swift-markdown/Sources/Markdown/Markdown.docc`
--fallback-display-name SwiftDocC
--fallback-bundle-identifier org.swift.SwiftDocC 
--fallback-bundle-version 1.0.0
--additional-symbol-graph-dir xx/swift-markdown.build/Debug/Markdown.build/symbol-graph

and see a list of warnings.
4. Run

docc convert swift-markdown/Sources/Markdown/Markdown.docc`
--fallback-display-name SwiftDocC
--fallback-bundle-identifier org.swift.SwiftDocC 
--fallback-bundle-version 1.0.0
--additional-symbol-graph-dir xx/swift-markdown.build/Debug/Markdown.build/symbol-graph
--warnings-as-errors

and see all the warnings are treated as errors.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[Kyle-Ye]

@swift-ci please test

[ethan-kusters]

Looks great! Thank you for opening this Kyle. Do you mind starting a thread on the Swift Forums about the intended user-experience here? Something along the lines of: https://forums.swift.org/t/adding-links-to-source-files-in-swift-docc/58587.

I think we should let folks on the forums weigh in on the naming and behavior of command-line option.

[Kyle-Ye]

Looks great! Thank you for opening this Kyle. Do you mind starting a thread on the Swift Forums about the intended user-experience here? Something along the lines of: https://forums.swift.org/t/adding-links-to-source-files-in-swift-docc/58587.

I think we should let folks on the forums weigh in on the naming and behavior of command-line option.

Yes, that's great. The forum post is here.

https://forums.swift.org/t/add-support-for-warnings-as-errors/59832

[Kyle-Ye]

@swift-ci please test macOS

[Kyle-Ye]

@swift-ci please test

[Kyle-Ye]

@swift-ci please test

[Kyle-Ye]

Update naming according to the forum post feedback. Could you help review this? @franklinsch

[franklinsch]

This is looking really great, thanks @Kyle-Ye! Just have a few minor bits of feedback.

[Kyle-Ye]

@swift-ci please test

[Kyle-Ye]

Rebase to main and add a new commit to fix the comment suggestions cc @franklinsch

[Kyle-Ye]

@swift-ci please test

[Kyle-Ye]

@d-ronnqvist Any other Code Review suggestion for this? If you are OK with it, I'll merge it this Sunday.

[Kyle-Ye]

@swift-ci please test macOS

[d-ronnqvist]

@d-ronnqvist Any other Code Review suggestion for this? If you are OK with it, I'll merge it this Sunday.

No other suggestions. Thanks.

[Kyle-Ye]

@swift-ci please test

[tinder-cfuller]

How to treat warnings as errors when using docbuild for iOS?

xcodebuild docbuild -scheme "Example" -destination "generic/platform=iOS"

[Kyle-Ye]

How to treat warnings as errors when using docbuild for iOS?

xcodebuild docbuild -scheme "Example" -destination "generic/platform=iOS"

This question is better asked in Apple's Developer forums or via a DTS. @tinder-cfuller

But anyway I have tried it on Xcode 15.2 and the following answer should apply.

• For Xcode GUI:
  • First locate - Build Settings - Documentation Compiler Options - Other DocC Flags
  • Then add --warnings-as-errors to the field list

• For xcodebuild:
  • Set OTHER_DOCC_FLAGS to --warnings-as-errors
  • You can also get the full command in your Xcode GUI's build log.

[tinder-cfuller]

@Kyle-Ye Thank you for your thorough answer! While this may not have been the best place for me to ask, the excellent info you provided may help others who end up here looking for the same thing. Thank you for taking the time to comment!! Very much appreciated. ⭐