Skip to content

Commit

Permalink
README trailing spaces
Browse files Browse the repository at this point in the history
  • Loading branch information
natikgadzhi committed Jul 6, 2023
1 parent 1d61565 commit 6e31c34
Showing 1 changed file with 32 additions and 32 deletions.
64 changes: 32 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
> ```
Expand Down

0 comments on commit 6e31c34

Please sign in to comment.