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.
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.
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.
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.
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
environmentscript 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..
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.
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.
| link |
| Stars: 1094 |
| Last commit: 3 hours ago |
typeDetails information from symbol graphs. by @pdwilson12 in https://github.com/apple/swift-docc/pull/529@PageColor directive by @ethan-kusters in https://github.com/apple/swift-docc/pull/525mode_t by @compnerd in https://github.com/apple/swift-docc/pull/600DirectoryMonitor on Windows temporarily by @compnerd in https://github.com/apple/swift-docc/pull/606Signal on Windows by @compnerd in https://github.com/apple/swift-docc/pull/605#if os check on Package.swift file by @Kyle-Ye in https://github.com/apple/swift-docc/pull/614XCTUnwrap over forced unwrappng by @compnerd in https://github.com/apple/swift-docc/pull/619setenv and unsetenv by @compnerd in https://github.com/apple/swift-docc/pull/610sleep with Thread.sleep(forTimeInterval:) by @compnerd in https://github.com/apple/swift-docc/pull/616@TitleHeading directive by @emilyychenn in https://github.com/apple/swift-docc/pull/611.docc extension by @MaxDesiatov in https://github.com/apple/swift-docc/pull/585ExternalLocationReference url property public and mutable by @ethan-kusters in https://github.com/apple/swift-docc/pull/627@PageKind sets the kind for the documentation node by @QuietMisdreavus in https://github.com/apple/swift-docc/pull/626LMDB.Environment on finalize(_:_:_:) by @compnerd in https://github.com/apple/swift-docc/pull/646TestFileSystem's handling of paths by @compnerd in https://github.com/apple/swift-docc/pull/655-o option as a shortcut for --output-path by @MaxDesiatov in https://github.com/apple/swift-docc/pull/682ValidationError text in DirectoryPathOption.swift by @MaxDesiatov in https://github.com/apple/swift-docc/pull/677extensionTo and declaredIn relationships to add extensions to path hierarchy by @d-ronnqvist in https://github.com/apple/swift-docc/pull/727$ORIGIN from installed docc ELF executable runpath (#738) by @finagolfin in https://github.com/apple/swift-docc/pull/741optionalMemberOf symbol under the correct container symbol (#760) by @d-ronnqvist in https://github.com/apple/swift-docc/pull/762/(_:_:) operators (#717) by @d-ronnqvist in https://github.com/apple/swift-docc/pull/772@DisplayName for a non-symbol (#783) by @d-ronnqvist in https://github.com/apple/swift-docc/pull/790@DeprecationSummary content (#784) by @d-ronnqvist in https://github.com/apple/swift-docc/pull/789Full Changelog: https://github.com/apple/swift-docc/compare/swift-5.9.2-RELEASE...swift-5.10-RELEASE
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics