From ad29e6676bca520bdcdfe8d3a7b6d3f01dfee130 Mon Sep 17 00:00:00 2001 From: Natik Gadzhi Date: Thu, 6 Jul 2023 09:25:37 -0700 Subject: [PATCH] README trailing spaces --- README.md | 64 +++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 18c8cd9c1b..b81f984eaa 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Swift-DocC -Swift-DocC is a documentation compiler for Swift frameworks and packages aimed +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 +For an example of Swift-DocC in action, check out [developer.apple.com](https://developer.apple.com/documentation). Much of Apple's developer documentation, from [Reference documentation](https://developer.apple.com/documentation/GroupActivities) @@ -22,35 +22,35 @@ the best place to get help with Swift-DocC and discuss future plans. ## Writing and Publishing Documentation with Swift-DocC -If you're looking to write and publish documentation with Swift-DocC, +If you're looking to write and publish documentation with Swift-DocC, the best way to get started is with Swift-DocC's [user documentation](https://www.swift.org/documentation/docc). ## Technical Overview and Related Projects -Swift-DocC builds documentation by combining _Symbol Graph_ files containing API information +Swift-DocC builds documentation by combining _Symbol Graph_ files containing API information with a `.docc` Documentation Catalog containing articles and tutorials to create a final archive containing the compiled documentation. More concretely, Swift-DocC understands the following kinds of inputs: 1. _Symbol Graph_ files with the `.symbols.json` extension. - _Symbol Graph_ files are a machine-readable representation of a module's APIs, + _Symbol Graph_ files are a machine-readable representation of a module's APIs, including their documentation comments and relationship with one another. - 2. A Documentation Catalog with the `.docc` extension. + 2. A Documentation Catalog with the `.docc` extension. Documentation Catalogs can include additional documentation content like the following: - + - Documentation markup files with the `.md` extension. Documentation markup files can be used to extend documentation for symbols and to write free-form articles. - + - Tutorial files with the `.tutorial` extension. Tutorial files are used to author step-by-step instructions on how to use a framework. - + - Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`, and `.zip`. - - - An `Info.plist` file containing metadata such as the name of the documented module. + + - An `Info.plist` file containing metadata such as the name of the documented module. This file is optional and the information it contains can be passed via the command line. Swift-DocC outputs a machine-readable archive of the compiled documentation. @@ -66,27 +66,27 @@ project's technical documentation: ### Related Projects - - As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to + - As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to emit _Symbol Graph_ files as part of the compilation process. - + - [SymbolKit](https://github.com/apple/swift-docc-symbolkit) is a Swift package containing the specification and reference model for the _Symbol Graph_ File Format. - - - [Swift Markdown](https://github.com/apple/swift-markdown) is a - Swift package for parsing, building, editing, and analyzing + + - [Swift Markdown](https://github.com/apple/swift-markdown) is a + Swift package for parsing, building, editing, and analyzing Markdown documents. It includes support for the Block Directive elements that Swift-DocC's tutorial files rely on. - - - [Swift-DocC-Render](https://github.com/apple/swift-docc-render) + + - [Swift-DocC-Render](https://github.com/apple/swift-docc-render) is a web application that understands and renders Swift-DocC's _render JSON_ format. - + - [Xcode](https://developer.apple.com/xcode/) consists of a suite of tools that developers use to build apps for Apple platforms. Beginning with Xcode 13, Swift-DocC is integrated into Xcode with support for building and viewing documentation for your framework and its dependencies. - + ## Getting started with developing `docc` `docc` is the command line interface (CLI) for Swift-DocC and provides @@ -128,17 +128,17 @@ To run `docc`, run the following command: ```bash swift run docc ``` - + ### Installing into Xcode You can test a locally built version of Swift-DocC in Xcode 13 or later by setting the `DOCC_EXEC` build setting to the path of your local `docc`: 1. Select the project in the Project Navigator. - - 2. In the Build Settings tab, click '+' and then 'Add User-Defined Setting'. - - 3. Create a build setting `DOCC_EXEC` with the value set to `/path/to/docc`. + + 2. In the Build Settings tab, click '+' and then 'Add User-Defined Setting'. + + 3. Create a build setting `DOCC_EXEC` with the value set to `/path/to/docc`. The next time you invoke a documentation build with the "Build Documentation" button in Xcode's Product menu, your custom `docc` will be used for the build. @@ -160,19 +160,19 @@ the path you provded if it's set. ## Using `docc` to build and preview documentation The preferred way of building documentation for your Swift package is by using -the Swift-DocC Plugin, or if you're using Xcode, using the "Build Documentation" command. +the Swift-DocC Plugin, or if you're using Xcode, using the "Build Documentation" command. -Refer to instructions in the plugin's +Refer to instructions in the plugin's [documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/) to get started with [building](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-a-specific-target), [previewing](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation), and publishing your documentation to your [website](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online) or [GitHub Pages](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages). -Alternatively, you can manually generate symbol graph files and invoke `docc` directly. +Alternatively, you can manually generate symbol graph files and invoke `docc` directly. Refer to instructions in [CONTRIBUTING.md](/CONTRIBUTING.md#assembling-symbol-graphs-and-building-with-docc-directly). - + ## Versioning -Swift-DocC's CLI tool (`docc`) will be integrated into the Swift toolchain +Swift-DocC's CLI tool (`docc`) will be integrated into the Swift toolchain and follows the Swift compiler's versioning scheme. The `SwiftDocC` library is versioned separately from `docc`. `SwiftDocC` is under @@ -182,7 +182,7 @@ active development and source stability is not guaranteed. ### Submitting a Bug Report -Swift-DocC tracks all bug reports with +Swift-DocC tracks all bug reports with [GitHub Issues](https://github.com/apple/swift-docc/issues). When you submit a bug report we ask that you follow the [provided template](https://github.com/apple/swift-docc/issues/new?assignees=&labels=bug&template=BUG_REPORT.yml) @@ -191,7 +191,7 @@ and provide as many details as possible. > **Note:** You can use the [`environment`](bin/environment) script > in this repository to gather helpful environment information to paste > into your bug report by running the following: -> +> > ```sh > bin/environment > ```