hi all! over the past week, i’ve been rolling out a number of improvements to the swift-biome-powered docs at swiftinit.org.
improved caching and content delivery
a lot of the changes relate to cache control and content delivery. API documentation actually consists of generating a lot of pages — the swift standard library itself includes nearly 20,000 symbols alone! getting this to run on a t2.micro EC2 instance required quite a lot more engineering than i originally anticipated.
loaded module 'Dispatch' (from package 'swift')
loaded module 'Swift' (from package 'swift')
loaded module '_Concurrency' (from package 'swift')
loaded module '_Differentiation' (from package 'swift')
loaded module '_Distributed' (from package 'swift', bystanders: 'Swift')
loaded module '_MatchingEngine' (from package 'swift', bystanders: 'Swift')
loaded module '_StringProcessing' (from package 'swift', bystanders: 'Swift')
loaded module 'NIOConcurrencyHelpers' (from package 'swift-nio')
loaded module 'NIOCore' (from package 'swift-nio', bystanders: 'Swift', 'Dispatch', '_Concurrency')
loaded module 'NIOEmbedded' (from package 'swift-nio')
loaded module 'NIOHTTP1' (from package 'swift-nio', bystanders: 'NIOCore')
loaded module 'NIOPosix' (from package 'swift-nio')
loaded module 'NIOTLS' (from package 'swift-nio')
loaded module 'NIOWebSocket' (from package 'swift-nio', bystanders: 'Swift', 'NIOCore')
loaded module 'SystemPackage' (from package 'swift-system', bystanders: 'Swift')
loaded 22418 vertices and 24652 edges from 15 module(s)
initialized biome (9809 KB)
rendered 22433 articles (54862 KB)
note: 69 linter warnings(s) in module 'Dispatch'
note: 78 linter warnings(s) in module 'Swift'
note: 17 linter warnings(s) in module '_Concurrency'
note: 1 linter warnings(s) in module '_MatchingEngine'
note: 40 linter warnings(s) in module 'NIOCore'
note: 18 linter warnings(s) in module 'NIOEmbedded'
note: 1 linter warnings(s) in module 'NIOPosix'
note: 16 linter warnings(s) in module 'SystemPackage'
loaded documentation
older versions of the site served most of the pages completely statically. however, this doesn’t really scale well in a multi-module, integrated API reference, because swift modules can, and frequently do, extend the namespaces of other modules. it wasn’t previously possible to say, view the documentation for String and show different members depending on if the viewer has enabled the Foundation module.
as part of a larger re-architecting, swift-biome now serves most types of pages semi-statically. this means it will soon be possible to filter symbol listings based on module imports! the swift-biome engine has also gotten a lot more memory-efficient, which is important at the moment because the t2.micro AWS machines only have ~650 MB of memory available for swift.
more modules! more packages!
the swiftinit.org docs have gone from offering just three modules to fifteen:
standard-library
swift-nio
swift-system
grouping deprecated and unavailable symbols
swift-biome now lists deprecated, obsoleted, and unavailable members in a separate section at the end of an API reference page. (example)
if the availability is by swift version, it will display the swift version: (example)
cross-module extensions
swift-biome can handle types that library authors place in the namespaces of types from other modules! (example)
in this situation, swift-biome shows both the declaring module name and the vendor module name in the top-right corner.
module lists
you can now use the red scope links (example) in the top-right corner to navigate vertically through an API! as you can see in in the screengrab below, you can click the scope links to get to the module root, where it turns into a link to the package root, where you’ll see a list of package targets:
follow the project!
you can check out the github repos for swift-biome and now, the swift-biome-index which contains the symbols graphs for the modules on swiftinit.org! as always, feedback and suggestions are welcome and encouraged!