search

ml-explore / mlx-swift

Swift API for MLX
https://ml-explore.github.io/mlx-swift/
MIT License
472 stars 35 forks source link

Xcode documentation navigation issue #14

Open Kyle-Ye opened 4 months ago

Kyle-Ye commented 4 months ago

We should avoid using hardcoded absolute link in Documentation bundle.

The result is the web version is fine but build and open the documentation in Xcode will give us a bad navigation experience - Opening a new web tab instead of navigating the corresponding page.

Also it will increase the cost when we want to deploy our documentation in other platform other than GitHub page. (eg. SwiftPackageIndex)

davidkoski commented 4 months ago

Are you referring to the links between the packages? I couldn't figure out any other way to get them -- it looks like the cross package links are still in the future.

We could potentially switch them to relative links. That would fix the hosting issue I think, but not viewing in Xcode docs.

Kyle-Ye commented 4 months ago

Are you referring to the links between the packages? I couldn't figure out any other way to get them -- it looks like the cross package links are still in the future.

Got it. I'm tracking this on the swift-docc side. It is indeed not supported currently on the upstream.

Once we are ready, we'll revisit the issue here.

davidkoski commented 4 months ago

I think the relative links will work for SPI. I added a .spi.yml file to indicate what to build for SwiftPackageIndex.

I think the remaining issue is the inability to do cross-package links that will work in the Xcode documentation viewer.