Skip to content

Commit 7f881ee

Browse files
sofiaromoralessofiaromorales
authored
README update (#695)
docs: README updates. - Moved build instructions to CONTRIBUTING.md - Added DocC help command to the README - Moved technical and related projects info from README to CONTRIBUTING - Updated year in DocC footer for CONTRIBUTING.md and README.md rdar://114318669
1 parent d756924 commit 7f881ee

File tree

2 files changed

+107
-151
lines changed

2 files changed

+107
-151
lines changed

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ more details.
4949

5050
## Building Swift-DocC
5151

52+
`docc` is the command line interface (CLI) for Swift-DocC and provides
53+
support for generating and previewing documentation.
54+
5255
### Prerequisites
5356

5457
Swift-DocC is a Swift package. If you're new to Swift package manager,
@@ -99,7 +102,7 @@ You can run your newly built version of `docc` with:
99102
```
100103
101104
Or, in Xcode, run the `docc`
102-
[scheme](https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/ManagingSchemes.html).
105+
[scheme](https://developer.apple.com/documentation/xcode/customizing-the-build-schemes-for-a-project).
103106
104107
### Miscellaneous
105108
@@ -261,7 +264,7 @@ export DOCC_HTML_DIR="/path/to/swift-docc-render-artifact/dist"
261264

262265
The `docc preview` command performs a conversion of your documentation and
263266
starts a local web server to allow for easy previewing of the built documentation.
264-
It monitors the provided Documentation Catalog for changes and updates the preview
267+
It monitors the provided documentation catalog for changes and updates the preview
265268
as you're working.
266269
267270
```sh
@@ -436,4 +439,65 @@ page.
436439
Once you've found an issue to work on,
437440
follow the above instructions for [Building Swift-DocC](#building-swift-docc).
438441
439-
<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
442+
## Technical Overview and Related Projects
443+
444+
Swift-DocC builds documentation by combining _Symbol Graph_ files that contains API information
445+
with a `.docc` documentation catalog that contains articles and tutorials
446+
to create a final archive with the compiled documentation.
447+
448+
More concretely, Swift-DocC understands the following kinds of inputs:
449+
450+
1. _Symbol Graph_ files with the `.symbols.json` extension.
451+
_Symbol Graph_ files are a machine-readable representation of a module's APIs,
452+
including their documentation comments and relationship with one another.
453+
454+
2. A documentation catalog directory with the `.docc` extension.
455+
Documentation catalogs can include additional documentation content like the following:
456+
457+
- Documentation markup files with the `.md` extension. Documentation markup files can
458+
be used to write articles and to extend documentation for symbols.
459+
460+
- Tutorial files with the `.tutorial` extension. Tutorial files are used to author
461+
step-by-step instructions on how to use a framework.
462+
463+
- Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`,
464+
and `.zip`.
465+
466+
- An `Info.plist` file containing metadata such as the name of the documented module.
467+
This file is optional and the information it contains can be passed via the command line.
468+
469+
Swift-DocC outputs a machine-readable archive of the compiled documentation.
470+
This archive contains _render JSON_ files, which fully describe the contents
471+
of a documentation page and can be processed by a renderer such as
472+
[Swift-DocC-Render](https://github.com/apple/swift-docc-render).
473+
474+
For more in-depth technical information about Swift-DocC, please refer to the
475+
project's technical documentation:
476+
477+
- [`SwiftDocC` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdocc/)
478+
- [`SwiftDocCUtilities` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdoccutilities/)
479+
480+
### Related Projects
481+
482+
- As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to
483+
emit _Symbol Graph_ files as part of the compilation process.
484+
485+
- [SymbolKit](https://github.com/apple/swift-docc-symbolkit) is a Swift package containing
486+
the specification and reference model for the _Symbol Graph_ File Format.
487+
488+
- [Swift Markdown](https://github.com/apple/swift-markdown) is a
489+
Swift package for parsing, building, editing, and analyzing
490+
Markdown documents. It includes support for the Block Directive elements
491+
that Swift-DocC's tutorial files rely on.
492+
493+
- [Swift-DocC-Render](https://github.com/apple/swift-docc-render)
494+
is a web application that understands and renders
495+
Swift-DocC's _render JSON_ format.
496+
497+
- [Xcode](https://developer.apple.com/xcode/) consists of a suite of
498+
tools that developers use to build apps for Apple platforms.
499+
Beginning with Xcode 13, Swift-DocC is integrated into Xcode
500+
with support for building and viewing documentation for your framework and
501+
its dependencies.
502+
503+
<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

‎README.md‎

Lines changed: 40 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,180 +1,67 @@
11
# Swift-DocC
22

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

66
For an example of Swift-DocC in action, check out
77
[developer.apple.com](https://developer.apple.com/documentation).
88
Much of Apple's developer documentation,
99
from [Reference documentation](https://developer.apple.com/documentation/GroupActivities)
1010
to [Tutorials](https://developer.apple.com/tutorials/swiftui),
11+
and [long-form content](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/)
1112
is built using Swift-DocC.
1213

14+
To learn more about the essentials of this tool
15+
refer to the
16+
[user documentation](https://www.swift.org/documentation/docc).
17+
1318
Swift-DocC is being actively developed. For more information about the
1419
Swift-DocC project, see the introductory blog post
1520
[here](https://swift.org/blog/swift-docc/).
1621

17-
The latest documentation for the Swift-DocC project is available
18-
on [Swift.org](https://swift.org/documentation/docc).
19-
20-
The [Swift Forums](https://forums.swift.org/c/development/swift-docc) are
21-
the best place to get help with Swift-DocC and discuss future plans.
22-
23-
## Writing and Publishing Documentation with Swift-DocC
24-
25-
If you're looking to write and publish documentation with Swift-DocC,
26-
the best way to get started is with Swift-DocC's
27-
[user documentation](https://www.swift.org/documentation/docc).
28-
29-
## Technical Overview and Related Projects
30-
31-
Swift-DocC builds documentation by combining _Symbol Graph_ files containing API information
32-
with a `.docc` Documentation Catalog containing articles and tutorials
33-
to create a final archive containing the compiled documentation.
34-
35-
More concretely, Swift-DocC understands the following kinds of inputs:
36-
37-
1. _Symbol Graph_ files with the `.symbols.json` extension.
38-
_Symbol Graph_ files are a machine-readable representation of a module's APIs,
39-
including their documentation comments and relationship with one another.
40-
41-
2. A Documentation Catalog with the `.docc` extension.
42-
Documentation Catalogs can include additional documentation content like the following:
43-
44-
- Documentation markup files with the `.md` extension. Documentation markup files can
45-
be used to extend documentation for symbols and to write free-form articles.
46-
47-
- Tutorial files with the `.tutorial` extension. Tutorial files are used to author
48-
step-by-step instructions on how to use a framework.
49-
50-
- Additional documentation assets with known extensions like `.png`, `.jpg`, `.mov`,
51-
and `.zip`.
52-
53-
- An `Info.plist` file containing metadata such as the name of the documented module.
54-
This file is optional and the information it contains can be passed via the command line.
55-
56-
Swift-DocC outputs a machine-readable archive of the compiled documentation.
57-
This archive contains _render JSON_ files, which fully describe the contents
58-
of a documentation page and can be processed by a renderer such as
59-
[Swift-DocC-Render](https://github.com/apple/swift-docc-render).
60-
61-
For more in-depth technical information about Swift-DocC, please refer to the
62-
project's technical documentation:
63-
64-
- [`SwiftDocC` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdocc/)
65-
- [`SwiftDocCUtilities` framework documentation](https://apple.github.io/swift-docc/documentation/swiftdoccutilities/)
66-
67-
### Related Projects
68-
69-
- As of Swift 5.5, the [Swift Compiler](https://github.com/apple/swift) is able to
70-
emit _Symbol Graph_ files as part of the compilation process.
71-
72-
- [SymbolKit](https://github.com/apple/swift-docc-symbolkit) is a Swift package containing
73-
the specification and reference model for the _Symbol Graph_ File Format.
74-
75-
- [Swift Markdown](https://github.com/apple/swift-markdown) is a
76-
Swift package for parsing, building, editing, and analyzing
77-
Markdown documents. It includes support for the Block Directive elements
78-
that Swift-DocC's tutorial files rely on.
79-
80-
- [Swift-DocC-Render](https://github.com/apple/swift-docc-render)
81-
is a web application that understands and renders
82-
Swift-DocC's _render JSON_ format.
83-
84-
- [Xcode](https://developer.apple.com/xcode/) consists of a suite of
85-
tools that developers use to build apps for Apple platforms.
86-
Beginning with Xcode 13, Swift-DocC is integrated into Xcode
87-
with support for building and viewing documentation for your framework and
88-
its dependencies.
89-
90-
## Getting started with developing `docc`
22+
## Getting Started with DocC
9123

9224
`docc` is the command line interface (CLI) for Swift-DocC and provides
93-
support for converting and previewing DocC documentation.
94-
95-
### Prerequisites
96-
97-
DocC is a Swift package. If you're new to Swift package manager,
98-
the [documentation here](https://swift.org/getting-started/#using-the-package-manager)
99-
provides an explanation of how to get started and the software you'll need
100-
installed.
101-
102-
DocC requires Swift 5.5 which is included in Xcode 13.
103-
104-
### Build
25+
support for generating and previewing documentation.
10526

106-
1. Checkout this repository using:
27+
There are multiple ways you can make use of DocC depending on your use case:
10728

108-
```bash
109-
git clone https://github.com/apple/swift-docc.git
110-
```
29+
**1. For documenting packages via SwiftPM:**
11130

112-
2. Navigate to the root of the repository with:
113-
114-
```bash
115-
cd swift-docc
116-
```
117-
118-
3. Finally, build DocC by running:
119-
120-
```bash
121-
swift build
122-
```
123-
124-
### Run
125-
126-
To run `docc`, run the following command:
127-
128-
```bash
129-
swift run docc
130-
```
131-
132-
### Installing into Xcode
133-
134-
You can test a locally built version of Swift-DocC in Xcode 13 or later by setting
135-
the `DOCC_EXEC` build setting to the path of your local `docc`:
31+
If you want to generate documentation for your Swift package we recommend using the Swift-DocC Plugin. Please
32+
refer to the Plugin's [documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/) to get started with
33+
[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),
34+
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).
13635

137-
1. Select the project in the Project Navigator.
138-
139-
2. In the Build Settings tab, click '+' and then 'Add User-Defined Setting'.
140-
141-
3. Create a build setting `DOCC_EXEC` with the value set to `/path/to/docc`.
36+
**2. For standalone documentation:**
14237

143-
The next time you invoke a documentation build with the "Build Documentation"
144-
button in Xcode's Product menu, your custom `docc` will be used for the build.
145-
You can confirm that your custom `docc` is being used by opening the latest build
146-
log in Xcode's report navigator and expanding the "Compile documentation" step.
38+
If you have Xcode installed, it's recommended to generate documentation using the `xcrun` command.
39+
You can get DocC working by invoking `xcrun docc` in your terminal.
14740

148-
### Invoking `docc` from Swift Package Manager
41+
Swift-DocC is also included in the Swift toolchain for both macOS and Linux.
14942

150-
You can also test a locally built version of Swift-DocC using the Swift Package
151-
Manager from the command line. The Swift-DocC SwiftPM plugin will try to read
152-
`DOCC_EXEC` environment variable value, and use the path you provded if it's set.
43+
To see instructions on how to use DocC from the CLI run
44+
```
45+
docc --help
46+
```
15347

154-
1. In your project's `Package.swift`, add a dependency on the [`Swift-DocC Plugin`](https://github.com/apple/swift-docc-plugin).
155-
2. Set the `DOCC_EXEC` environment variable and run the documentation generation
156-
command:
48+
**3. For documenting apps, frameworks, and packages using Xcode:**
15749

158-
```bash
159-
DOCC_EXEC=/path/to/docc swift package generate-documentation
160-
```
50+
If you want to generate an API reference for your project you can use DocC via Xcode.
51+
Please refer to the Xcode [documentation](https://developer.apple.com/documentation/xcode/writing-documentation)
52+
to learn the essentials of how to get started.
16153

162-
## Using `docc` to build and preview documentation
54+
## Writing and Publishing Documentation with Swift-DocC
16355

164-
The preferred way of building documentation for your Swift package is by using
165-
the Swift-DocC Plugin, or if you're using Xcode, using the "Build Documentation" command.
56+
If you want to learn how to write and format your documentation please refer to
57+
[Formatting Your Documentation Content](https://www.swift.org/documentation/docc/formatting-your-documentation-content).
58+
For publishing go to [Distributing Documentation to Other Developers](https://www.swift.org/documentation/docc/distributing-documentation-to-other-developers).
16659

167-
Refer to instructions in the plugin's
168-
[documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)
169-
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),
170-
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).
60+
To learn more about how Swift-DocC works internally please see [CONTRIBUTING.md](CONTRIBUTING.md).
17161

172-
Alternatively, you can manually generate symbol graph files and invoke `docc` directly.
173-
Refer to instructions in [CONTRIBUTING.md](/CONTRIBUTING.md#assembling-symbol-graphs-and-building-with-docc-directly).
174-
17562
## Versioning
17663

177-
Swift-DocC's CLI tool (`docc`) will be integrated into the Swift toolchain
64+
Swift-DocC's CLI tool (`docc`) is integrated into the Swift toolchain
17865
and follows the Swift compiler's versioning scheme.
17966

18067
The `SwiftDocC` library is versioned separately from `docc`. `SwiftDocC` is under
@@ -200,7 +87,7 @@ and provide as many details as possible.
20087
20188
If you can confirm that the bug occurs when using the latest commit of Swift-DocC
20289
from the `main` branch (see [Building Swift-DocC](/CONTRIBUTING.md#building-swift-docc)),
203-
that will help us track down the bug faster.
90+
it will help us track down the bug faster..
20491
20592
### Submitting a Feature Request
20693
@@ -217,6 +104,11 @@ before being enabled by default.
217104
218105
## Contributing to Swift-DocC
219106
220-
Please see the [contributing guide](/CONTRIBUTING.md) for more information.
107+
The [Swift Forums](https://forums.swift.org/c/development/swift-docc) are
108+
the best place to get help with Swift-DocC and discuss future plans.
109+
110+
As an open-source project, we value any contribution made to this tool.
111+
Please see the [contributing guide](/CONTRIBUTING.md) for more information on how to
112+
contribute and build DocC from source.
221113
222-
<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
114+
<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

0 commit comments

Comments
 (0)