The Android Workgroup meeting today discussed the desire to improve the documentation around Swift on Android. Please use this topic to discuss what you feel should be added or clarified.
One precedent we might follow is https://docs.swift.org/embedded/documentation/embedded, which appears to be sourced from https://github.com/swiftlang/swift-embedded-examples/tree/main/Sources/EmbeddedSwift/Documentation.docc.
Since we already have https://github.com/swiftlang/swift-android-examples, maybe we could just start adding some docs into a new Documentation.docc folder there. Some topics that were mentioned in the meeting:
- Porting considerations (
canImport(Android), 32-bit Int sensitivity, importingFoundationEssentialsrather thanFoundation, etc.) - How to run test cases locally and/or in CI
- How to set up the Android emulator (or at least pointers to the official docs at https://developer.android.com/)
- How to package JNI libraries into an app
- List some community projects (like the https://github.com/swift-android-sdk/swift-android-native package we discussed)
I don't know how the docs get from swift-embedded-examples into docs.swift.org, since that build mechanism doesn't appear to be part of any public repo that I can find. Perhaps someone from the @swift-website-workgroup or @swift-documentation-workgroup knows and can advise?
1 Like
@mishal_shah helped set that up for us in embedded-examples. I'm also curious about how it works since we want to add more code-gen steps to our docs gen
1 Like
I wonder if we need a general "platforms" area that is the umbrella for projects like this?
I love the idea of having all this on docs.swift.org, by the way -- but it would be nice to avoid partitioning Swift into different subprojects. It's not "Swift for Android", "Swift for Server", "Swift for Embedded", obviously -- all this is what Swift itself is.
1 Like
@compnerd raised what I think was a similar concern on the meeting call- tough to say for sure, as we didn't have time to really dig into the details, and I thought a text venue like GitHub would be better for that deep dive anyway- but realistically, we do need some place to lay out the differences between platforms.
For example, I have proposed a non-Darwin porting guide for Swift packages, that would lay out the general principles of importing the different platform overlays, then list some specific issues that often hit each platform. I think everybody is on board with that, we just need to put it together.
I don't think anybody is suggesting whole separate books on Swift for Server or Wasm, or putting the entire Android NDK API reference on swift.org, as Saleem seemed to be concerned we wanted to do.
Another good example is that Embedded Swift is a subset of the language: it would be good to lay out exactly what that means somewhere, in detail.
Swift is now one of the most cross-platform of the popular programming languages, we need to document that and make more of a case for such cross-platform use publicly:
"this release still sends a clear signal: Swift is evolving from a language centered around Apple platforms into a more general-purpose language with cross-platform and system-level capabilities. The continued progress of Embedded Swift, Android support, and the unification of the SwiftPM build system all point in this direction. For most iOS developers, the short-term impact may feel limited, but in the long run, this is a foundational update paving the way for what comes next."
From Apple's perspective, I could see this selling a bunch more Macs, eg if Swift on linux combined with linux Containerization for macOS becomes the easiest way for server devs to write performant cloud services. I don't expect Apple to ever go full-bore and port SwiftUI to Windows or whatever, 
but we can push OSS Swift onto more platforms.
1 Like
I've been working with Mishal to re-work this whole flow and publish a combined set of documentation, which includes the embedded examples and an equivalent bit from Wasm that was recently added.
There's support for building from packages in the docs repo - where it package aligns to a catalog, and those catalogs all get bundled together - the PR that pulls and merges them all we just merged, but it's not yet on any path for building and publishing - there's a bit more CI/infrastructure work to integrate all these pieces, including the work that Chris and the others are doing to get the Standard Library content all assembled as a DocC catalog and resulting archive as well.
For reference, the build process (and it's workflow) are in swiftlang/docs - merged in with script and data to build the combined collection of docs by heckj · Pull Request #72 · swiftlang/docs · GitHub, and the relevant script today at scripts/build_docs.py, all meant to be triggered in a GitHub action workflow
If you check out the script, you'll see a sources.json that identifies a bunch of different repositories across swiftlang from which to grab content, where it clones the repo content and builds the docs, then merges them all together.
@rauhul if you poke in the script, you'll see a pre-flight script option, which is actively being used with swift-book, that may provide exactly what you're after. Adding one is adding the script to the target repo and updating the sources to reference the script to run before the script invokes the build process for the docs)
As I've been working on updating the migrating the legacy server guides, it's become quite clear that they're really far more about using Swift on Linux than server specific (although there's obviously some overlap), so the initial doc structure that's up there may well need or want to change to reflect either a collection for all platforms together, or a catalog specific to a platform with the whole collection published together.
Right now I'm focused on getting this new structure and publishing pipeline set up, including aligning the whole thing to provide versioned content by Swift release, and it looks good to be able to use Swift 6.3 as the first "release" that we collect together.
In some respects - from the Embedded and Wasm example repositories - we're already separating content by catalogs by "platform" (with the nod that Embedded is not a platform, more a collection of many and it's own thing that isn't easily tossed in such a box). One of the issues we have today is that the content is very unevenly covered across the platforms - with some having quite a bit, and others quite little.
In any case, I heard loud and clear that the Android group would like a place to host more documentation, and potentially examples to go along with them, and pushed that discussion upwards to both the platform steering group and core team. One of the questions at hand is where do we draw the line around what we include in the "docs for Swift as an open source project" and especially for any platform specific content, that kind of needs a clear answer to move forward.
The groups are actively talking about this, but I don't have clear answers to present as to current or future direction, what fits into this, and who should be set as the code owners for a new directory in the docs repo to support this content.
2 Likes
Thank you for the very enlightening overview of where the docs are at and where they are going, as well as the pointers to how the current doc build process is working.
Even Android defies narrow platform classification: many instances are handsets that run traditional consumer apps distributed through app stores and whatnot, but many other devices are bespoke hardware running some AOSP variant with a subset of capabilities and their own mechanisms for how they manage software, more closely akin to "embedded". "Android" is more of an umbrella term, much like "UNIX" could encompass Linux, *BSD, and Darwin platforms.
I imagine that organizing documentation for such fuzzy taxonomies will always be a challenge.
We discussed this again at the Android Workgroup meeting today. There is clearly a strong desire for a place to start assembling docs related to Swift development on Android, so I've gone ahead and followed the Swift embedded precedent by adding a similar structure to the swift-android-examples repository:
I understand that the documentation publication pipeline is currently undergoing reassessment, but in the interest in having a near term solution, I feel that this is as good a landing spot as anywhere else. And once a new documentation workflow is in place, we can follow along with whatever swift-embedded-examples winds up doing with their docs.
1 Like