Swiftinit updates: February 2024

taylorswift · February 26, 2024, 9:24pm

hi all, Unidoc 0.8 has been released and deployed to the Swiftinit documentation index.

previous updates:

January 2024

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/@TechnologyRoot can 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 nofollow from links to trusted domains, such as swift.org or wikipedia.org.
The symbol graph linker now includes @_spi symbols, 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 ephemeral 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 @_spi declarations.
The documentation server no longer sends unnecessary headers with 304 Not Modified responses.
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.