Code links for modules in a package are broken in SPI documentation

[wigging]

I’m using DocC for a Swift package. Unfortunately, the documentation generated on Swift Package Index screws up the code links as seen in Level 1 BLAS section on this page. These links work fine when I build the documentation with Xcode but not on Swift Package Index. Here is the markdown file in the GitHub repository that is used for the documentation page. Since this works in Xcode docs but not on SPI docs then I guess it is a bug or maybe there is a different way I should define the link. Any suggestions on how to get these links to work in Xcode and Swift Package Index or is it a bug with SPI?

Below is a screenshot of how the documentation page looks when building the docs with Xcode. Notice the links in the Level 1 BLAS section correctly render in the Xcode version of the docs. Clicking each link takes you to the correct documentation page for that method or function.

[daveverwer]

Thanks for this @wigging.

Can you show me how this looks when you build the documentation for the web rather than for Xcode? We don't change the CSS of the DocC renderer at all, we only insert a header/footer and very carefully style that in a way that should not affect the DocC content at all.

I checked the styling we're rendering and I can see the code styles are all there and the only thing being overridden is the user/default stylesheet and nothing from SPI is getting in the way:

If you could build HTML documentation locally and pop a screenshot in if it looks different, that would be really useful. It would be useful in figuring out if this is related to SPI or might be a bug in the DocC renderer.

Thanks!

[daveverwer]

If you could also include a screenshot of how it looks in the Xcode renderer, too. That would also be useful. Thanks!

[wigging]

I added a screenshot to the original post (see above) that shows the documentation page as built with Xcode. How do I build the HTML documentation locally? In Xcode it gives me an Export option which generates a .doccarchive file. This archive opens with Xcode and the docs look the same as if I built directly in Xcode.

[daveverwer]

There's some documentation here: https://www.swift.org/documentation/docc/distributing-documentation-to-other-developers#Host-a-Documentation-Archive-on-Your-Website

[daveverwer]

Thanks for the screenshot and additional information, @wigging, I didn't realise that the links themselves were missing. I thought this was a styling issue from your first message.

I'm taking a quick look at this in more detail now.

[wigging]

Correct, the links don't work at all when viewing the SPI documentation. They work fine when viewing the Xcode documentation as shown in the screenshot image.

[daveverwer]

So I built the documentation locally without using any of our tools and the documentation renders exactly the same as we show them on the hosted version.

However, I know why this is not working as you expect. Those symbols in that list are not defined in the target that's having its documentation generated and so it doesn't know what to link to at that time.

Do we have a workaround for this, @finestructure?

[wigging]

Can you share the steps you used to generate this? I read the link you shared above but I just get a page not found error when I try to view the HTML.

[finestructure]

Do we have a workaround for this, @finestructure?

I don't think we do. I believe Swift 6.1 might bring improvements here but I'm currently still in the process of trying to get Swift 6.1 to work for us. Perhaps we can revisit this once we land 6.1 support.

[wigging]

It looks like the 6.1 builds are running on the SPI so I checked the documentation and the links are still broken. See this page where the items in the list should link to vector instance methods in the code:
https://swiftpackageindex.com/wigging/numerix/main/documentation/numerix/linearalgebra

[wigging]

I flattened the file structure of the package and made it one target. The layout works better with DocC and the documentation renders fine on Swift Package Index. But thanks for the help.