Releases: tayloraswift/swift-unidoc
0.8.0
Unidoc 0.8.0 was focused on improving support for rich media and structured tutorials, in line with what the DocC tool supports.
✂️ Snippets
Unidoc 0.8.0 now supports Swift Snippets, as specified in SE-0356. A complex example of Snippets in use can be found in the newly-published swift-png documentation.
Snippets support captions and slicing, and can display inline source citations if the documentation has been associated with a GitHub repository.
🎩 Tutorials
Unidoc 0.8.0 now supports structured tutorials, specifically, the @Tutorials, @Tutorial, and @Article block directives familiar to DocC users. Unidoc 0.8.0 can diff and highlight @Code blocks, similar to DocC. Like Snippets, tutorial code can also display inline source citations when linked to a GitHub repository.
Unidoc 0.8.0 also supports rich media, and can now display GitHub-hosted images inline in rendered documentation.
Most of the newly-supported block directives are available in all forms of documentation, not just @Tutorial blocks. The full list of supported block directives is:
@Article@Chapter@Code@Comment@Column@ContentAndMedia@Documentation@DocumentationExtension@Downloads@Forums@Image@Intro@IsRoot*@Metadata@Resources@Row@SampleCode@Section@Snippet@Stack@Steps@Step@TechnologyRoot*@TutorialReference@Tutorial@Tutorials@Video@Videos@Volume
Note:
@IsRoot/@TechnologyRootcan be detected and validated, but currently has no effect.
A live example of a rendered tutorial can be found in SwiftSyntax By Example.
🪞 Other improvements and bug fixes
- We improved the quality of the symbol graph compiler’s diagnostics, and associated more of the emitted diagnostics with source locations.
- We added tests and fixed a number of bugs in the cross-package link resolver.
- We added some optimization passes to the symbol graph compiler which should result in slightly smaller documentation archives.
- We added support for linkable
- term <term name>:lists. - The symbol graph compiler can now detect magical aside blocks in nested markup regions (#143 notwithstanding).
- The symbol graph linker can now sanitize external links, rewrite references to Apple Developer Docs if it can find a local copy of the target documentation, and remove
nofollowfrom links to trusted domains, such asswift.orgorwikipedia.org. - The symbol graph linker now includes
@_spisymbols, deprecated symbols, and typealiases in fuzzy search results. (We received feedback that these symbols are actually quite common search subjects, as developers are frequently searching for information about “gray” API.) This will be gradually rolled out on Swiftinit over the coming weeks. - The symbol graph linker can now compress search archives with gzip, which may improve performance for some clients.
- The symbol graph linker can now resolve cross-package references to inherited symbols, such as
Int.max(FixedWidthInteger.max). doc:links now behave identically regardless of syntax (<doc:_>vs[anchor text](doc:_)) used.- The rendered documentation now includes OpenGraph metadata tags.
- The rendered documentation no longer displays a second “Symbols” pie chart for documentation coverage, as this was entirely redundant.
- The rendered documentation now displays statistics about
@_spideclarations. - The documentation server no longer sends unnecessary headers with
304 Not Modifiedresponses. - We improved the appearance of wide code blocks on mobile.
- We tweaked the package scoring algorithm so that popular open source packages now get updated even more frequently.
0.7.0
there are few obvious user-facing changes in this release, but a lot has shifted around in the code base since 0.6.
- Symbol graph build system now correctly runs
git submodule update --init - Symbol graph compiler can now recover from a Swift compiler crash (which sadly happens all too often…)
- Symbol graph compiler now uses a separate scratch directory from
.build, which should make it easier to run it in a docker container - Trailing slashes are now allowed in the Unidoc codelink format
- Admins can now inspect all of the package names and aliases associated with a package
- Admins can now change the preferred name of a package
- Server-side symbol graph linker now runs in the background as needed
- Server-side symbol graph linker can now export compiled symbol graphs to Amazon S3, which should greatly reduce the amount of disk space Unidoc requires
- Server-side symbol graph linker can now compress compiled symbol graphs with DEFLATE
- Admins can now view total server error (5xx) count
- Admins can now view global
mongodping times - Admins can now manually uplink symbol graphs from the web UI
- Uplinking old documentation no longer generates new activity feed entries
- Fixed #123
- Symbol graph compiler now supports packages with dots in their names
- Symbol graph compiler can now collect information about available version-specific Package.swift manifests, and displays it in the web UI
- Added quick links to the web UI homepage
- Web server now queries from the fastest available
mongodreplica (when replication is enabled), which should reduce the amount of times people see pictures of Margot Robbie crying - Upgraded
swift-mongodbdependency to obtain some critical MongoDB driver bugfixes - Enum cases are now displayed in a separate section in the web UI
- Protocol requirements now also benefit from autogenerated ‘See also’ sections
- Admins can now change
robots.txtwithout restarting the server - TikTok Bytespider is now blacklisted by default (sorry ByteDance)
- Adjusted the package scoring formula (we are slowly becoming swiftpackageindex :( )
@available(obsoleted)symbols now render in grayed-out font in the web UI
0.6.0
See release notes on the Swift Forums
0.3.0
🚠 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
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
⌨️ 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.
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
️⛳️ 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:)
✨ 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.
0.2.4
New in Unidoc 0.2.4:
Swift 5.9 support
Unidoc now supports (and requires) Swift 5.9.
HTTP/2 support
The Unidoc server now supports (and prefers) HTTP/2 over HTTP/1.1.
GitHub crawling
Unidoc can now crawl GitHub periodically to index git tags and update repository metadata.
Git tag dashboard
The Git Tags dashboard has been improved.
0.2.2
New in 0.2.2.
🚠 Per-symbol migration banners
Unidoc 0.2.2 can query successors for symbols in older (and prerelease) documentation snapshots, 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
If the symbol does not exist in the latest stable release, Unidoc will only display a link to the package documentation root.