SwiftDocC

swift-5.10-RELEASE

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
apple/swift-docc

What's New

Swift 5.10 Release

2024-03-06T16:07:11Z

What's Changed

  • Use a custom scheme for local "Declared In" source file URLs by @d-ronnqvist in #513
  • enable Doxygen support by default by @QuietMisdreavus in #519
  • Add support for multipart HTTP request bodies by @pdwilson12 in #514
  • Fix rare crash when tutorial file has same as documentation bundle identifier by @d-ronnqvist in #517
  • Add request argument to opt-out of source file path information by @d-ronnqvist in #526
  • Process typeDetails information from symbol graphs. by @pdwilson12 in #529
  • Update DocC setup instructions by @franklinsch in #511
  • Fix a crash when a protocol with a default implementation is aliased with the same name by @d-ronnqvist in #534
  • Add authoring support for a @PageColor directive by @ethan-kusters in #525
  • Disfavor default implementations and synthesized symbols in link collisions by @d-ronnqvist in #540
  • Store only the resolved reference in DocumentationContext.symbolIndex by @d-ronnqvist in #543
  • Fix rendering issue for links with special characters by @d-ronnqvist in #532
  • Fix inverse logic in hierarchy based link resolver environment opt-out by @d-ronnqvist in #548
  • [ConvertService] Support resolving images referenced in content by @d-ronnqvist in #539
  • Fix test that took seconds to type check by @d-ronnqvist in #547
  • Correctly set page color metadata for symbol pages by @ethan-kusters in #549
  • drop an "Extended Symbol" page when its children are curated elsewhere by @QuietMisdreavus in #541
  • Remove deprecated usages of 'layout' API of 'ContentAndMedia' in docs by @Saafo in #531
  • Render extended symbol pages with their extended module by @QuietMisdreavus in #557
  • Label Sample-Code Call-to-Action buttons with "View Source" by @ethan-kusters in #566
  • Match documentation extensions to symbols using link resolver by @d-ronnqvist in #565
  • Provide ConvertService with mapping of USRs to minimal access level required for extended documentation to be available by @daniel-grumberg in #555
  • Revert support for module-relative documentation extension links by @d-ronnqvist in #574
  • Expand documentation for new layout directives by @daniel-grumberg in #576
  • Support resolving code file references in ConvertService by @d-ronnqvist in #570
  • Better support for relative links when multiple symbols in the hierarchy have the same name by @d-ronnqvist in #578
  • Add successfully resolved external references to reference index by @d-ronnqvist in #582
  • Support building this repo for more platforms, by checking the build triple by @finagolfin in #500
  • Prefer non-symbols in general documentation links by @d-ronnqvist in #594
  • LMDB: introduce a typealias for mode_t by @compnerd in #600
  • Benchmark: implement memory query for Windows by @compnerd in #598
  • build: fix dependencies by @compnerd in #599
  • FoundationExtensions: enable autoreleasepool on Windows by @compnerd in #602
  • Model: enable concurrent rendering on Windows by @compnerd in #601
  • Utility: add a Windows path to the synchronisation support by @compnerd in #603
  • build: remove the PreviewServer on Windows by @compnerd in #604
  • Update distribution documentation static environment enhancements by @d-ronnqvist in #587
  • Various small documentation phrasing updates by @d-ronnqvist in #590
  • Update content formatting documentation with symbol link enhancements by @d-ronnqvist in #588
  • Utility: disable DirectoryMonitor on Windows temporarily by @compnerd in #606
  • Utility: disable Signal on Windows by @compnerd in #605
  • build: bump swift-docc-plugin to 1.2.0 for Windows by @compnerd in #607
  • build: split the SwiftDocCUtilitiesTest for Windows by @compnerd in #608
  • docc: indicate Windows as being supported by @compnerd in #609
  • Fix preview issue on macOS and Linux by @Kyle-Ye in #613
  • Fix Package.resolved syncing issue with Package.swift by @Kyle-Ye in #612
  • Remove #if os check on Package.swift file by @Kyle-Ye in #614
  • Tests: adjust synchronization tests for Windows by @compnerd in #615
  • Fix a crash when linking to a symbol that doesn't have a page by @d-ronnqvist in #617
  • Tests: use XCTUnwrap over forced unwrappng by @compnerd in #619
  • Tests: treat Windows as Linux by @compnerd in #620
  • SwiftDocCUtilitiesTests: add wrappers for setenv and unsetenv by @compnerd in #610
  • Tests: replace sleep with Thread.sleep(forTimeInterval:) by @compnerd in #616
  • keep the original URL when decoding Download/ExternalLocationReference by @QuietMisdreavus in #621
  • Add authoring support for @TitleHeading directive by @emilyychenn in #611
  • Converter: allow converting a directory w/o .docc extension by @MaxDesiatov in #585
  • Make ExternalLocationReference url property public and mutable by @ethan-kusters in #627
  • Tests: add a missed case of Windows exclusion by @compnerd in #629
  • @PageKind sets the kind for the documentation node by @QuietMisdreavus in #626
  • Tests: adjust LMDB test harness for Windows by @compnerd in #631
  • don't crash on an extension with an empty declaration by @QuietMisdreavus in #635
  • Tests: disable the LogHandle tests on Windows by @compnerd in #634
  • Finalize the diagnostic engine if an error is thrown by @d-ronnqvist in #637
  • deprecate ExternalLocationReference in favor of DownloadReference by @QuietMisdreavus in #638
  • False positive warning when curating symbol with special character by @d-ronnqvist in #642
  • Navigator: close the LMDB.Environment on finalize(_:_:_:) by @compnerd in #646
  • Make visitLineBreak return new line instead of space by @Kyle-Ye in #633
  • Allow certain directives by @emilyychenn in #641
  • Allow anchor doc:#heading within same article by @natikgadzhi in #652
  • Indexing: add a workaround for clearing the index by @compnerd in #647
  • Remove the cache based link resolver by @d-ronnqvist in #624
  • Fix typo assesment -> assessment by @stzn in #445
  • SwiftDocCUtilitiesTests: adjust TestFileSystem's handling of paths by @compnerd in #655
  • Document using DOCC_EXEC in SwiftPM by @natikgadzhi in #653
  • encode an explicit null for DownloadReference's checksum by @QuietMisdreavus in #656
  • Add i18n feature flag to ThemeSettings schema by @marinaaisa in #475
  • Improve default diagnostic formatter by @arthurcro in #535
  • Create file URLs for bundle files in TestFileSystem by @d-ronnqvist in #661
  • only use the last file component when deciding decoding strategy by @QuietMisdreavus in #665
  • Miscellaneous test changes to avoid making assumptions about what's a valid URL by @d-ronnqvist in #586
  • Tests: enable the non-Darwin behaviour on Windows by @compnerd in #671
  • Tests: standardize both sides of the URL by @compnerd in #670
  • Fix regression where sample code pages stopped respecting manual curation by @ethan-kusters in #674
  • Fix 2 links in documentation comments by @d-ronnqvist in #680
  • Allow -o option as a shortcut for --output-path by @MaxDesiatov in #682
  • Fix tiny grammatical typo by @gwynne in #667
  • Fix ValidationError text in DirectoryPathOption.swift by @MaxDesiatov in #677
  • Correctly use UTF-8 indices when highlighting diagnostic source by @arthurcro in #683
  • No pages warning by @sofiaromorales in #664
  • SwiftDocC: handle arc separator on Windows by @compnerd in #673
  • SwiftDocC: implement mime type sniffing for Windows by @compnerd in #686
  • SwiftDocCUtilities: repair the Windows build by @compnerd in #693
  • Split PathHierarchy implementation into different files. by @d-ronnqvist in #662
  • README update by @sofiaromorales in #695
  • [5.10] Update swift-markdown and fix test case by @Kyle-Ye in #709
  • [5.10] Use extensionTo and declaredIn relationships to add extensions to path hierarchy by @d-ronnqvist in #727
  • [5.10] Fix render node decoder for single-article documentation archives by @sofiaromorales in #731
  • [5.10] Check symbols are deprecated on at least one platform before marking unconditionally deprecated by @mayaepps in #728
  • [5.10] Remove error for mixed symbol graph formats. by @d-ronnqvist in #725
  • [5.10] Fix a bug where the diagnostics file dropped all conversion problems by @d-ronnqvist in #724
  • [5.10] Documentation - Typos & Consistency Fixes by @patshaughnessy in #721
  • [5.10] Use new SwiftPM flag to remove $ORIGIN from installed docc ELF executable runpath (#738) by @finagolfin in #741
  • [5.10] Fix duplicated diagnostic issue by @Kyle-Ye in #746
  • [5.10] Correct source code locations of link diagnostics for Objective-C doc comments (#734) by @patshaughnessy in #747
  • [5.10] Fix symbol link parsing bug for disambiguated subtraction operators by @d-ronnqvist in #750
  • [5.10] Structural changes to the DocCDocumentation Catalog (#742) by @sofiaromorales in #758
  • [5.10] Fix crash where multi-language symbols could get parents not in the tree by @d-ronnqvist in #761
  • [5.10] Add optionalMemberOf symbol under the correct container symbol (#760) by @d-ronnqvist in #762
  • [5.10] Include manually curated non-symbol nodes in the Topics section regardless of the source language of the symbol by @sofiaromorales in #764
  • [5.10] Fix bugs with symbol links to /(_:_:) operators (#717) by @d-ronnqvist in #772
  • [5.10] Fix regression where DocC no longer emits warnings for unresolved links. by @sofiaromorales in #775
  • [5.10] Update allowed years in check-source script by @d-ronnqvist in #791
  • [5.10] Fix a crash when configuring a @DisplayName for a non-symbol (#783) by @d-ronnqvist in #790
  • [5.10] Support resolving links in @DeprecationSummary content (#784) by @d-ronnqvist in #789
  • [5.10] Fix link syntax issue in public documentation page (#787) by @d-ronnqvist in #792
  • [5.10] Replace spaces with dashes in links to articles by @d-ronnqvist in #796
  • [5.10] Fix problem where API Collections had no roleHeading assigned. by @sofiaromorales in #795

New Contributors

Full Changelog: swift-5.9.2-RELEASE...swift-5.10-RELEASE

Swift-DocC

Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation

For an example of Swift-DocC in action, check out developer.apple.com. Much of Apple's developer documentation, from Reference documentation to Tutorials, and long-form content is built using Swift-DocC.

To learn more about the essentials of this tool refer to the user documentation.

Swift-DocC is being actively developed. For more information about the Swift-DocC project, see the introductory blog post here.

Getting Started with DocC

docc is the command line interface (CLI) for Swift-DocC and provides support for generating and previewing documentation.

There are multiple ways you can make use of DocC depending on your use case:

1. For documenting packages via SwiftPM:

If you want to generate documentation for your Swift package we recommend using the Swift-DocC Plugin. Please refer to the Plugin's documentation to get started with building, previewing, and publishing your documentation to your website or GitHub Pages.

2. For standalone documentation:

If you have Xcode installed, it's recommended to generate documentation using the xcrun command. You can get DocC working by invoking xcrun docc in your terminal.

Swift-DocC is also included in the Swift toolchain for both macOS and Linux.

To see instructions on how to use DocC from the CLI run

docc --help

3. For documenting apps, frameworks, and packages using Xcode:

If you want to generate an API reference for your project you can use DocC via Xcode. Please refer to the Xcode documentation to learn the essentials of how to get started.

Writing and Publishing Documentation with Swift-DocC

If you want to learn how to write and format your documentation please refer to Formatting Your Documentation Content. For publishing go to Distributing Documentation to Other Developers.

To learn more about how Swift-DocC works internally please see CONTRIBUTING.md.

Versioning

Swift-DocC's CLI tool (docc) is integrated into the Swift toolchain and follows the Swift compiler's versioning scheme.

The SwiftDocC library is versioned separately from docc. SwiftDocC is under active development and source stability is not guaranteed.

Bug Reports and Feature Requests

Submitting a Bug Report

Swift-DocC tracks all bug reports with GitHub Issues. When you submit a bug report we ask that you follow the provided template and provide as many details as possible.

Note: You can use the environment script in this repository to gather helpful environment information to paste into your bug report by running the following:

bin/environment

If you can confirm that the bug occurs when using the latest commit of Swift-DocC from the main branch (see Building Swift-DocC), it will help us track down the bug faster..

Submitting a Feature Request

For feature requests, please feel free to file a GitHub issue or start a discussion on the Swift Forums.

Don't hesitate to submit a feature request if you see a way Swift-DocC can be improved to better meet your needs.

All user-facing features must be discussed in the Swift Forums before being enabled by default.

Contributing to Swift-DocC

The Swift Forums are the best place to get help with Swift-DocC and discuss future plans.

As an open-source project, we value any contribution made to this tool. Please see the contributing guide for more information on how to contribute and build DocC from source.

Description

  • Swift Tools 5.6.0
View More Packages from this Author

Dependencies

Last updated: Thu Mar 28 2024 13:07:16 GMT-0900 (Hawaii-Aleutian Daylight Time)