swift-unidoc

0.8.0

scalable, multi-package documentation engine for the swift language
tayloraswift/swift-unidoc

What's New

0.8.0

2024-02-26T21:13:32Z

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.

image

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.

image

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 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 @_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.

unidoc
0.7

ci build status

Unidoc is a scalable documentation engine for the Swift language. Unidoc can be thought of as a multi-target analogue to Apple’s local DocC compiler. It is designed for long-lived, centralized documentation indices that store, link, and serve multiple versions of documentation for many Swift packages at once.

Unidoc powers the Swiftinit open source package index!

Features

🪶 Small archive sizes

Unidoc servers are designed to store versioned documentation indefinitely. To achieve this, Unidoc uses a stable binary symbol graph format that can be up to two orders of magnitude smaller than an equivalent DocC archive.

Here’s a comparison for the (in)famous SwiftSyntax package, at version 508.0.1:

Archive Size File count
DocC (uncompressed, including synthesized symbols) 708.0 MB 84,619
DocC (uncompressed, stripping synthesized symbols) 155.0 MB 17,537
Unidoc (uncompressed, including synthesized symbols) 7.8 MB 1
Unidoc (tar.xz, including synthesized symbols) 611.4 KB 1

DocC numbers sourced from Slack

⬆️ Evolving documentation

You can regenerate Unidoc documentation from symbol graph archives without recompiling documentation from package sources, which historically was a major bottleneck in the DocC workflow. In many situations, this means you can easily upgrade Unidoc documentation to take advantage of new features even if the underlying symbol graph was compiled by an older version of Unidoc.

You can re-link Unidoc documentation against newer versions of their package (and standard library) dependencies as they are released, without recompiling the symbol graph from source.

Unidoc databases use a cellular architecture which allows you to stagger documentation upgrades across a package index without taking the server offline.

🔗 Cross-package references

Unidoc can validate and resolve cross-package symbol links, including links to symbols in the standard library. This means you can link to String in your documentation, and Unidoc will automatically generate a link to the standard library documentation for String.

Normal “IDE-style” symbol references, such as links to Int within function signatures, are also supported.

🕸 Cross-package extensions

Unidoc can display extensions, including third-party extensions, directly in the documentation for the extended type. This means you can view Channel members originating from packages such as swift-nio-ssl and swift-nio-http2 from the swift-nio documentation itself.

In the future, we hope to support finer-grained control over third-party extensions shown in extendee documentation.

💞 Inherited symbols

Because Unidoc is a multi-package documentation engine, it can track and display symbols inherited from protocols in upstream dependencies, including the standard library, at negligible storage cost. This means types in third-party libraries that conform to protocols such as Sequence can display and link to Sequence API in their member lists.

🌐 Unified database

Unidoc servers maintain a combined database of all documentation in their index. This allows Unidoc to serve (or redirect) individual symbol pages on-demand, instead of requiring clients to download enormous Vue.js indices for client-side rendering. This provides better performance for clients, and greatly reduces cache churn on the server as documentation is upgraded.

🔋 Lightweight HTML

Unidoc generates lightweight HTML documentation that uses CSS for the majority of its layout and interactivity, and serves a very low number of additional assets. This means Unidoc pages are responsive, accessible, cache-friendly, and render with minimal content-layout shift (CLS).

📜 Readable signatures

Unidoc symbol graphs include line-breaking markers computed by SwiftSyntax, which allows Unidoc to display long function signatures in a readable, line-wrapped format. This makes it much easier to scan long lists of symbols with complex signatures, such as the member list of SwiftSyntax’s AccessPathComponentSyntax.

🚠 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

️⛳️ Symbol disambiguation pages

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

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:)

🛸 Documentation coverage

Unidoc can compute documentation coverage on a per-package and per-module basis. You can view coverage levels as pie-chart visualizations on package and module pages; see swift-atomics’s package page for an example.

:octocat: GitHub integration

Unidoc can periodically index Git tags by querying the GitHub API. This feature requires a GitHub app registration and app secret and is not enabled by default. Unidoc can also load repository metadata from GitHub, and use it to generate permanent links to source code on GitHub if the underlying symbol graph includes source map information.

The Unidoc compiler builds symbol graph archives with source maps by default, even if GitHub integration is not available.

🔐 Secure administration

When GitHub integration is available, Unidoc can use social authentication to allow users to log in with their GitHub account and perform administrative actions.

As the Swiftinit index grows, we hope to allow package maintainers to claim ownership of their packages and manage their documentation directly through the Swiftinit website.

🔎 Search engine optimization (SEO)

Unidoc can generate, update, and serve sitemap files for search crawlers like Googlebot. This allows search engines to discover and index your documentation, and makes it easier for users to find your package.

Unidoc will make an effort to generate a <meta> description for every symbol in a package, even if the symbol has no documentation.

Unidoc avoids generating many copies of the same documentation, which can hinder visibility in search engines.

Description

  • Swift Tools 5.9.0
View More Packages from this Author

Dependencies

Last updated: Mon Dec 09 2024 16:47:27 GMT-1000 (Hawaii-Aleutian Standard Time)