Skip to content

0.3.0
Compare
Choose a tag to compare
@tayloraswift tayloraswift released this 26 Sep 22:11
· 1684 commits to master since this release
0.3.0
a6000fa
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

🚠 Per-symbol migration banners

The Unidoc server can now query successors for symbols in older (and prerelease) versions, and display a banner directing visitors to the symbol’s counterpart in the latest stable release of its package. This link is specific to the symbol, and comes with a corresponding <link rel="canonical"> element and HTTP header.

Example: https://swiftinit.org/docs/swift-nio:2.57.0/niocore/eventloopgroup

Firefox_Screenshot_2023-09-17T22-30-08 946Z

If the symbol does not exist in the latest stable release, Unidoc will only display the link to the package documentation root.

🔭 Version management

Stale documentation is a perennial problem that afflicts all package indexes in the swift community, including swiftinit. Index sites can fail to serve up-to-date documentation for a variety of reasons, and these reasons are generally opaque to the reader.

  • The index may be unaware that a package it mirrors has released a new version.

  • The index may be backlogged by other releases in the documentation build queue.

  • The index may be unable to build documentation due to bugs in its documentation compiler, or even the swift compiler itself.

To increase awareness of new releases and decouple version indexing from the build infrastructure, Unidoc 0.3 now features deepened GitHub integration enabling Unidoc servers to track release activity in near-real time.

This information is now surfaced to the public through /tags dashboards, which can be reached from the landing page for the documentation of any package.

Example: https://swiftinit.org/tags/swift-asn1

Firefox_Screenshot_2023-09-26T21-04-54 445Z

⌨️ DocC keyboard shortcuts

Unidoc’s front-end now supports the / keyboard shortcut for focusing the symbol search bar.

Although this is a relatively superficial change, it can be a significant ergonomic improvement, particularly if you have muscle memory from navigating DocC documentation.

image

The search bar can be defocused with the Esc key.

📂 Collapsible ‘See Also” sections

Very long ‘See Also’ sections are now collapsed by default. This is most relevant to packages with exceptionally bloated topics listings, such as SwiftSyntax.

Example: https://swiftinit.org/docs/swift-syntax/swiftsyntax/enumcaseparameterclausesyntax

image

️⛳️ Symbol disambiguation pages

Unidoc is able to serve symbol disambiguation pages under the 300 Multiple Choice HTTP status.

Although you should avoid creating ambiguous symbol links if possible, they are a natural occurrence as APIs evolve and overloads are added.

Example: https://swiftinit.org/docs/swift-certificates/x509/policyevaluationresult.failstomeetpolicy(reason:)

image

✨ Miscellaneous changes

We fixed some symbol link parsing bugs in the Unidoc compiler, improved the performance of some documentation queries, upgraded the project to Swift 5.9, enabled HTTP/2 support, and hardened the security of some of the server’s administrative endpoints.

Assets 2
Loading