swiftlang / swift-docc-render

Web renderer for Swift-DocC documentation.
Apache License 2.0
315 stars 53 forks source link

Render combined navigation for merged documentation archives #877

Closed mportiz08 closed 4 months ago

mportiz08 commented 5 months ago

Bug/issue #, if applicable: 124537023

Summary

Now that Swift-DocC can merge multiple documentation archives together into a single archive, it will provide navigator data that includes a combined index for all the pages in the archive. This change updates Swift-DocC-Render to render this combined data for all the pages in the navigator.

Example:

Screenshot 2024-07-09 at 1 12 50 PM

Dependencies

https://github.com/apple/swift-docc/pull/821

Testing

You can use this fixture which combines docs for Inner and Outer modules into a combined My Project archive: MyCombinedDocs.doccarchive.zip

Steps:

  1. Download/unzip the example MyCombinedDocs.doccarchive.zip fixture and checkout this branch of Swift-DocC-Render
  2. Run VUE_APP_DEV_SERVER_PROXY=/path/to/MyCombinedDocs.doccarchive npm run serve and open http://localhost:8080/documentation
  3. Verify that the top-level page for "My Project" loads at that URL and that the navigator has functional links to both the Inner and Outer docs
  4. Verify that navigation works normally and there are no regressions with routing behavior

Known DocC issue: the breadcrumb link to "My Project" from the getting started article doesn't work due to a bug with the compiler data pointing to the wrong URL (should be /documentation and not /documentation/my-project)

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

mportiz08 commented 4 months ago

Marking this as a draft PR for the moment after talking with @d-ronnqvist offline. I'll need to make some additional changes to support the situation where multiple modules have been bundled together under a parent module.

mportiz08 commented 4 months ago

I've updated the PR description with more up-to-date info and testing instructions. This should be ready now and ended up being simpler than I originally anticipated once I got access to some better fixture data :)

hqhhuang commented 4 months ago

@swift-ci test