Add Code docs with jazzy

[philipphofmann]

Description

Use https://github.com/realm/jazzy to create code docs similar to, for example, https://alamofire.github.io/Alamofire/. CI should automatically update these.

[philipphofmann]

Maybe consider https://developer.apple.com/documentation/docc instead.

[kevinrenskers]

I can generate API documentation from within Xcode perfectly fine (Product -> Build Documentation), but I can't make it work from the command line, see https://stackoverflow.com/questions/74263875/using-docc-for-an-objective-c-project. Waiting for someone to answer that question and then it should be very quick to close this issue as done :)

[philipphofmann]

Did you, @kevinrenskers, try the xcodebuild docbuild command, see https://developer.apple.com/documentation/xcode/distributing-documentation-to-external-developers?

[kevinrenskers]

That only creates the documentation archive, not the rendered website.

[github-actions[bot]]

This issue has gone three weeks without activity. In another week, I will close it.

But! If you comment or otherwise update it, I will reset the clock, and if you label it Status: Backlog or Status: In Progress, I will leave it alone ... forever!

---

"A weed is but an unloved flower." ― Ella Wheeler Wilcox 🥀

[philipphofmann]

Maybe worth checking out @kevinrenskers https://stackoverflow.com/questions/71199393/how-can-i-publish-on-github-using-docc. If using DocC, please consider --enable-inherited-docs, see https://forums.swift.org/t/what-is-the-impact-effect-of-the-enable-inherited-docs-with-docc-convert/53812

[kevinrenskers]

The problem is that it doesn't seem to work for Obj-C projects.

[philipphofmann]

Oh now 🙈

[philipphofmann]

The DocC documentation compiler converts Markdown-based text into rich documentation for Swift and Objective-C projects, and displays it right in the Xcode documentation window.

https://developer.apple.com/documentation/docc. At least their docs state it should work.

[kevinrenskers]

Did you look at https://stackoverflow.com/questions/74263875/using-docc-for-an-objective-c-project, which I posted a while ago?

[kevinrenskers]

I'll try it with xcodebuild instead with the --transform-for-static-hosting flag, see if that makes a difference

[philipphofmann]

https://stackoverflow.com/questions/74263875/using-docc-for-an-objective-c-project

Nope sorry I didn't 😁

[kevinrenskers]

It sorta works and I have a PR: https://github.com/getsentry/sentry-cocoa/pull/2445. But my recommendation is to probably use Jazzy after all as DocC really works a lot better with Swift projects.

[github-actions[bot]]

This issue has gone three weeks without activity. In another week, I will close it.

But! If you comment or otherwise update it, I will reset the clock, and if you label it Status: Backlog or Status: In Progress, I will leave it alone ... forever!

---

"A weed is but an unloved flower." ― Ella Wheeler Wilcox 🥀

[philipphofmann]

Investigation PR https://github.com/getsentry/sentry-cocoa/pull/2490.

[philipphofmann]

Maybe a useful blog post on DocC: https://pspdfkit.com/blog/2024/generating-api-documentation-for-multiple-targets-with-docc/.