Generate static website docs from swift components

[gruberb]

This PR is a first step in building static-website docs for the Swift components produced by application-services.

It adds a new folder inside automation. Inside, we build a new Swift project, with all the .swift and .h files from the output of uniffi-bindgen. We have to manipulate a few things to make it work, and provide a fixed module.modulemap and Package.swift.

In the end, we use jazzy to generate the documentation.

Next steps

This is WIP, the next step is to add this to the CI, and find a domain or another way to host this.

Feedback

I decided to move this to this repo instead of rust-components-swift, because it feels closer to the source, and we really just need the output of uniffi-bindgen to build this. No Xcframework or Xcodeproject needed.

Outcome (local)

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 22.00%. Comparing base (66bfc0b) to head (098eee0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6354      +/-   ##
==========================================
- Coverage   22.64%   22.00%   -0.64%     
==========================================
  Files         327      342      +15     
  Lines       29846    30712     +866     
==========================================
  Hits         6759     6759              
- Misses      23087    23953     +866     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[mhammond]

We briefly discussed UDL yesterday, so it's worth pointing out that the fxa-client crate has extensive docs in UDL which we should make sure are rendered. I believe some edits will be needed though as their is a mix of /// and // comments there and IIRC, only triple slash docs are extracted.

[gruberb]

We briefly discussed UDL yesterday, so it's worth pointing out that the fxa-client crate has extensive docs in UDL which we should make sure are rendered. I believe some edits will be needed though as their is a mix of /// and // comments there and IIRC, only triple slash docs are extracted.

I didn't want to include an upgrade to uniffi = "0.28.1, because I think that's a different issue. I can though if we want. I quickly tested it locally, and yes, the doc comments (///) are extracted and shown in the output docs:

We can open a PR to upgrade uniffi and adjust all the UDL comments to be /// instead of //? Can also do it in this PR.

[gruberb]

I requested to use ruby/setup-ruby for this repository: https://bugzilla.mozilla.org/show_bug.cgi?id=1915656

[gruberb]

@bendk I simplified the Cargo.toml a lot (diff), and we directly use the megazords/ios-rust dependencies now.

The static website lives in the swift-docs branch for now: https://github.com/mozilla/application-services/tree/swift-docs

We have one last challenge: Where do we host this? Different options.

• We can use subfolders in the docs branch. Which means we have to integrate this workflow with the generate-docs workflow. We then create a subfolder there called swift-docs, which we then can link.
• We create a new repository, called uniffi-docs, where we also host the topic guides, and push it there.

The problem with both is: We cannot host multiple GitHub pages domains for a single repository.

[bendk]

We can use subfolders in the docs branch. Which means we have to integrate this workflow with the generate-docs workflow. We then create a subfolder there called swift-docs, which we then can link.

I like this option. We only want one static site in the end, so we may as well put everything in one branch. You could either adjust this PR or do that in a follow up, either way is fine with me. I think the branch is called gh-pages though right?