search

swiftlang / swift-docc-plugin

Swift Package Manager command plugin for Swift-DocC
https://swiftpackageindex.com/swiftlang/swift-docc-plugin/documentation/swiftdoccplugin
Apache License 2.0
317 stars 54 forks source link

Feat: New plugin flag for skipping synthesized symbols #28

Closed sofiaromorales closed 1 year ago

sofiaromorales commented 2 years ago

Bug/issue #, if applicable: #27

Summary

This pull request aims to support the generation of archives without synthesized symbols by passing a new plugin flag --skip-synthesized-symbols. This would reduce the size of the generated doccarchive.

The plugin flag --skip-synthesized-symbols has been added to achieve this. It doesn't transform any of the passed arguments but overrides the default value of symbolGraphOptions.includeSynthesized to false. Also, with the proposed implementation, more flags could be added to override other settings of the symbol graph options.

Dependencies

N/A

Testing

For automated testing run the integration tests suite.

For manual testing:

  1. Download the attached package
  2. In Package.swift set the right path for swift-docc-plugin dependency
  3. Run swift package generate-documentation, and swift package generate-documentation --skip-synthesized-symbols, for both compare the files generated at PackageWithConformanceSymbols.doccarchive/data/documentation/packagewithconformancesymbols/bar

PackageWithConformanceSymbols.zip

Checklist

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

ethan-kusters commented 1 year ago

Hi @sofiaromorales would you mind taking a look at the merge conflicts here when you have a chance? I believe #34 introduced a few since it also touches some of this same code.

It would be great to land this in the next release alongside extension support if we can.

ethan-kusters commented 1 year ago

@swift-ci please test

ethan-kusters commented 1 year ago

CC: @theMomax I'm having trouble adding you as reviewer for some reason – but would appreciate your review on this as well.

theMomax commented 1 year ago

@ethan-kusters that's probably because I don't have commit access to Swift repositories and thus cannot formally approve a PR.

As for the review, I think it looks good! One thing I didn't check, though, is whether the symbolGraphOptions.includeSynthesized property has existed since 5.6. I do think so, but otherwise we'd need some special handling for backwards compatibility as I added it in #34.

ethan-kusters commented 1 year ago

@swift-ci please test