Investigate creating API documentation for iOS Prebid SDK

[bretg]

We would like to utilize SwiftDocC in Prebid SDK, but running into a problem.

I read various sources for how to get SwiftDocC set up:

https://github.com/apple/swift-docc
https://developer.apple.com/documentation/xcode/documenting-apps-frameworks-and-packages

What I gathered is that there are 2 steps: first, create a 'symbol graph' using the main compiler, then build the docs using the documentation compiler:

% swift package dump-symbol-graph
% docc convert MyDocs.docc

However, running this on Prebid SDK ends in failure because the codebase is mixed Swift and ObjC:

% swift package dump-symbol-graph
error: 'prebid-mobile-ios': target at '~/git/prebid-mobile-ios/PrebidMobile' contains mixed language source files; feature not supported

I also tried the instructions given in the README of this repo to build the SDK using ./scripts/buildPrebidMobile.sh, but that also fails:

ERROR:  While executing gem ... (Errno::EACCES)
    Permission denied @ rb_sysopen - /Library/Ruby/Gems/2.6.0/gems/ffi-1.16.3/CHANGELOG.md

Perhaps this is related to open issue #978 ? Anyhow, not clear that running buildPrebidMobile.sh would help the documentation effort. The goal of this issue is to find if there's a way to resolve the "mixed language" error. Found a reference that suggests splitting the swift/objc code apart. Or maybe there's a way to compile the symbol graph besides the swift package command?

Note that we need to do this from the command line in the long run because we're going to want to script the update of the documentation if it's going to be useful. i.e. I'm not as interested if there's an involved process of setting up an IDE that works. If the process of publishing API reference changes requires a lot of effort, it won't get done and the online docs will fall behind.

[YuriyVelichkoPI]

Hi @bretg !

I was able to generate the docs right from the Xcode running Product -> Build Documentation

Here how it looks in Xcode:

Unfortunately, due to the mixing of languages, there are too many public classes in the index table, so we should do some cleanup work before publishing.

Also, I'm attaching the exported doc archive. Use Show Package Context to see the files. It's basically a website inside. Will we be able to plug it into the current docs system?

PrebidMobile.doccarchive.zip

[YuriyVelichkoPI]

Looks like we can use following notation to exclude some Swift classes from the doc: https://github.com/apple/swift/blob/main/docs/ReferenceGuides/UnderscoredAttributes.md#_documentationvisibility-

still searching for an analog for ObjC

[bretg]

Sounds like nice progress @YuriyVelichkoPI , but can this be done from the command line? Otherwise the manual process of exporting from xcode is going to get tiresome and perhaps be forgotten.

[OlenaPostindustria]

Hi @bretg, @YuriyVelichkoPI !

I researched this issue and found a solution on how we can generate a DocC archive from CL:

xcodebuild docbuild -scheme PrebidMobile -destination 'name=iPhone 15 Pro' -derivedDataPath intermediates && \
DOC_PATH=$(find intermediates -type d -name '*.doccarchive') && \
xcrun docc process-archive transform-for-static-hosting "$DOC_PATH" --output-path generated-website

So basically we need to execute this script as a separate step in CI/CD.

[ValentinPostindustria]

Hello.

For Android we can use default Javadoc HTML documentation. We already generate this documentation for publishing Android AAR files to the Maven repository.
This command generates Javadoc HTML documentation in the PrebidMobile/PrebidMobile-core/build/docs/javadoc/.

./gradlew :PrebidMobile-core:javadoc

Another good option is Dokka documentation engine. It can convert the documentation to different formats: HTML, PDF and Markdown (2 different MD styles). Markdown formats can be used to create universal documentation with the same styles for Android and iOS systems.
Example of the Dokka MD (GFM) documentation: md.gfm.zip

[YuriyVelichkoPI]

Not sure about iOS, beacuse don't see a result, but in the archive for Android I see docs for all classes. But we don't need it for the SDK. We need documentation only for Public API which publisher face with.

Is it achievable with the proposed tools?

Pay attention that on iOS, due to the language mixing, we have a lot of false-public classes that shouldn't be exposed.

Is it ok if we add some additional script for removing the unneeded files from the final version?

[OlenaPostindustria]

@YuriyVelichkoPI It's basically the same you've sent before but files inside docarchive are extracted to separate folder. Yes we can write a script to remove some classes from the final version.

[YuriyVelichkoPI]

Hi @bretg !

Olena and Valentin are working on API documentation, and they have some intermediate results to review.

In short, they are adding the additional step to the Rerelease pipeline, which will generate the docs and put them into the repo. Eventually, the docs can be available via GitHub Pages.

Examples of the current resupts:
iOS: https://docs.prebid.org/prebid-mobile-ios/
Android https://docs.prebid.org/prebid-mobile-android/

API docs have different design. We didn't find a tool to make it the same for both platforms.

Also, we continue working on the description of the classes, methods, and properties. For now, a lot of entries don't have a description in the code.

So we would like to know your feedback about the relevance of the results. Are these docs good and the team should continue? Or the results don't match the expectations.

One more example. If API docs are released, we can use them in the general docs to describe, for example, fetchDemand() function.

Don't pay attention to the absence of a description; it is absent in the code base as well. In the scope of this work we will add description to all public items.

[bretg]

In my view, anything is way better than nothing, so this is major progress - thank you all.

Yuriy and I have been discussing the update implementation in Slack. There will be a workflow in each repo that will update the docs upon release. My take is that we should go ahead and release what we have when these workflows are complete and improve the contents over time.