rarestype / unidoc

🩷   **unidoc**   🩷 a scalable multi-package documentation engine for the swift language swiftinit home · get started locally 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! Requirements Unidoc supports Linux and macOS. Unidoc requires Swift 6.2. | Platform | Status | | -------- | ------| | 🐧 Linux (server) | | | 🐧 Linux | | | 🍏 Darwin | | Follow our quickstart guide to learn how to set up a local Unidoc server. Features ✏️ Powerful symbol links Unidoc supports the UCF symbol link syntax — a superset of the DocC symbol link syntax — which supports multi-component paths, cross-module references, and type signature disambiguation. | Syntax | Renders as | | ------ | ---------- | | Int.init(_:) (Float) | ?hash=2OSCB) | | Int.init(_:) (Double) | ?hash=8VBWO) | | Int/init(_:) (Double) | ?hash=8VBWO) | 🚦 Built for Continuous Integration The Unidoc documentation compiler can be run in CI mode to validate documentation and fail the pipeline if documentation errors (such as broken links) are diagnosed. The Unidoc compiler can diagnose *all* broken symbol links, including references to symbols in package dependencies and the standard library. We provide the swift-unidoc-action for GitHub Actions. ✂ Rich code snippets Unidoc can render SwiftPM code snippets in documentation with linked IDE-style code references and hover-over tooltips. See swiftonserver.com, which uses Unidoc as its rendering backend, for an example of code snippets in action. 🪶 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 ( , 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. 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 in your documentation, and Unidoc will automatically generate a link to the standard library documentation for . Normal “IDE-style” symbol references, such as links to 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 members originating from packages such as and from the 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 can display and link to 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 . 🚠 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 element and HTTP header. Example: ️⛳️ Symbol disambiguation pages Unidoc is able to serve symbol disambiguation pages under the 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: ) 🛸 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 ’s package page for an example. :octocat: GitHub integration Unidoc can perio…