Skip to content
This repository was archived by the owner on Jun 1, 2023. It is now read-only.

Commit b335ca0

Browse files
Lukas-StuehrkLukas-Stuehrk
committed
Add a user guide.
1 parent 76175f5 commit b335ca0

6 files changed

+588
-0
lines changed

‎Docs/00-introduction.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
`swift-doc` is a documentation generator for projects
2+
which are written in the Swift programming language.
3+
It collects all classes, structures, enumerations, and protocols
4+
as well as top-level type aliases, functions, and variables
5+
in a project's Swift source code.
6+
It also reads the comments in the source code
7+
and then renders a documentation
8+
which lists all declared symbols combined with their explanatory comments.
9+
10+
Because of this, `swift-doc` is the ideal tool to build documentation intended for the users of a Swift library,
11+
but it can also be used to generate the documentation of an iOS or macOS app.
12+
13+
Currently, there are two output formats available:
14+
15+
- **html**: Generates a website.
16+
17+
[Here you can find an example](https://swift-doc-preview.netlify.app/) of
18+
[SwiftMarkup's](https://github.com/SwiftDocOrg/SwiftMarkup) documentation rendered as a website.
19+
20+
- **commonmark**: Generates markdown files in the CommonMark markdown format.
21+
The files generated by `swift-doc` are build with specific file names
22+
and a specific folder structure,
23+
so they can be used for publication to your project's
24+
[GitHub Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis).
25+
26+
[Here you can find an example](https://github.com/SwiftDocOrg/Alamofire/wiki) of
27+
[Alamofire's](https://github.com/Alamofire/Alamofire/) documentation rendered in a GitHub wiki.
28+
29+
`swift-doc` only reads the Swift source code of a project.
30+
It does not need to compile or run the project
31+
to generate the documentation.
32+
Because of this, creating documentation with `swift-doc` is very fast.
33+
And you can run `swift-doc` on Linux to generate the documentation,
34+
even if the project would require building with Xcode on macOS.
35+
This can simplify building the documentation in your CI pipeline,
36+
because you don't need to execute it on a machine with macOS.
37+
38+
But this approach also comes with some downsides.
39+
As `swift-doc` only operates on the source code,
40+
it has some limitations:
41+
It can build documentation only for projects that are fully written in Swift.
42+
It can't build documentation for projects which have a codebase that has mixed Objective-C and Swift code.
43+
44+
This guide leads you through all the needed steps to set up `swift-doc`
45+
to generate a documentation for your project.
46+
It's split into the following parts:
47+
48+
1. [Set up swift-doc to generate documentation for your project](01-setup-swift-doc.md)
49+
1. [Using the GitHub action](01-github-action.md)
50+
2. [Using the command-line tool](01-command-line-tool.md)
51+
2. [Understand documentation comments](02-documentation-format.md)
52+
3. [Common problems when using swift-doc](03-common-problems.md)

‎Docs/01-command-line-tool.md

+214
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Using the command-line tool
2+
3+
`swift-doc` can be used from the command-line on macOS and Linux.
4+
5+
Before you can use `swift-doc`,
6+
you need to install it first.
7+
It's available via Homebrew and as a Docker container.
8+
Alternatively, you can always build it from sources.
9+
10+
## Installation
11+
### Homebrew
12+
13+
[Homebrew](https://brew.sh/)is a free and open-source package management for macOS and Linux.
14+
If you are using Homebrew,
15+
run the following command to install `swift-doc` using Homebrew:
16+
17+
```terminal
18+
$ brew install swiftdocorg/formulae/swift-doc
19+
```
20+
21+
### Docker
22+
23+
You can run `swift-doc` from the latest [Docker](https://www.docker.com) image with the following commands:
24+
25+
```terminal
26+
$ docker pull swiftdoc/swift-doc:latest
27+
$ docker run -it swiftdoc/swift-doc
28+
```
29+
30+
### Building from source
31+
32+
You can also build `swift-doc` from source.
33+
It is written in Swift and requires Swift 5.3 or later.
34+
Run the following commands to build and install from sources:
35+
36+
```terminal
37+
$ git clone https://github.com/SwiftDocOrg/swift-doc
38+
$ cd swift-doc
39+
$ make install
40+
```
41+
42+
`swift-doc` has a dependency on [libxml2](https://en.wikipedia.org/wiki/Libxml2).
43+
It also has an optional dependency on
44+
[Graphviz](https://www.graphviz.org/)
45+
if you want to generate the relationship graphs.
46+
47+
If you're on Linux,
48+
you may need to first install these prerequisites.
49+
You can install it on Ubuntu or Debian by running
50+
the following command:
51+
52+
```terminal
53+
$ apt-get update
54+
$ apt-get install -y libxml2-dev graphviz
55+
```
56+
57+
If you're on macOS,
58+
Graphviz is available via Homebrew:
59+
60+
```terminal
61+
$ brew install graphviz
62+
```
63+
64+
# Build your first documentation
65+
66+
Let's build some documentation,
67+
now that you have successfully installed `swift-doc`!
68+
You need to provide two arguments
69+
to build the documentation.
70+
71+
The first argument is the name of the module
72+
for which you build the documentation.
73+
Usually, you will provide a name that matches your package name.
74+
So if your Swift project is called `AwesomeSwiftLibrary`,
75+
you'd provide `AwesomeSwiftLibrary`
76+
as the name of the module.
77+
The module name is provided via the `--module-name` option.
78+
79+
Besides the module name,
80+
you need to provide paths to directories containing the Swift source files of your project.
81+
You need to provide at least one path to a directory,
82+
but you can provide as many as you want
83+
if your project is split into different directories.
84+
However, you don't need to provide subdirectories
85+
-- `swift-doc` will walk through all subdirectories in the provided directories
86+
and collect all Swift files from there.
87+
88+
> **Automatically excluded top-level directories**:
89+
> `swift-doc` tries to do the right thing by default
90+
> and it optimizes for use cases which are the most common in the Swift community.
91+
> Therefore, some top-level directories are excluded by default
92+
> because most likely you don't want to include those sources in your documentation.
93+
> Those excluded directories are:
94+
> - `./node-modules/`
95+
> - `./Packages/`
96+
> - `./Pods/`
97+
> - `./Resources/`
98+
> - `./Tests/`
99+
>
100+
> If you want to include those files in your documentation nevertheless,
101+
> you can always include a direct path to the directory
102+
> and they will be included.
103+
> So let's say you have a document structure like this:
104+
> ```
105+
> MyProject/
106+
> ├── Tests
107+
> └── OtherDirectory
108+
> ```
109+
> Then running
110+
> `swift-doc --module-name MyProject ./MyProject`
111+
> will only include the files in the subdirectory `OtherDirectory`
112+
> and automatically exclude the `Tests` subdirectory.
113+
> But running
114+
> `swift-doc --module-name MyProject ./MyProject ./MyProject/Tests`
115+
> will also include all files in the `Tests` subdirectory.
116+
117+
Let's run the command in the directory of your project.
118+
119+
```terminal
120+
$ swift-doc generate --module-name AwesomeSwiftLibrary ./Sources/
121+
```
122+
123+
And that's it!
124+
You successfully created the first documentation of your project.
125+
But where can you find it?
126+
127+
By default, `swift-doc` writes the generated documentation into the directory at `.build/documentation/`.
128+
You can provide a different output directory with the `--output` option:
129+
130+
```terminal
131+
$ swift-doc generate --module-name AwesomeSwiftLibrary ./Sources/ --output some/other/directory
132+
```
133+
134+
## Changing the output format to a rendered website.
135+
136+
If you followed the steps until now
137+
and checked the documentation which was created,
138+
you could see that `swift-doc` generated a collection of markdown files as output your documentation.
139+
Those markdown files are build with specific file names
140+
and with a specific folder structure,
141+
so they can be used for publication to your project's
142+
[GitHub Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis).
143+
144+
This might be not what you expected.
145+
Maybe you wanted to generate a website
146+
which you could publish on the internet as a documentation for the end users of your library?
147+
148+
This option is also provided by `swift-doc`.
149+
It's called the _output format_ and you can change it by setting the`--format` option.
150+
In order to generate a website,
151+
you need to set the option to `html`:
152+
153+
```terminal
154+
$ swift-doc generate --module-name AwesomeSwiftLibrary --format html ./Sources/
155+
```
156+
157+
## Choose which symbols are included by setting the access level
158+
159+
You might have noticed that the generated documentation contained less symbols that your library actually has.
160+
This is because `swift-doc` only includes public symbols by default
161+
— as this are also the symbols which are exposed to users of your library.
162+
163+
But if you want to generate documentation for apps and not only for libraries
164+
or if you want to generate a documentation for developers and not only end users of your library,
165+
then you might want to include additional symbols.
166+
167+
Therefore `swift-doc` also provides the possibility to decide which symbols are included
168+
by setting the minimum access level from which symbols should be included.
169+
This is done via the `--minimum-access-level` option.
170+
Its possible values are:
171+
172+
* `public` (default).
173+
This will only include symbols which are declared `public` or `open`.
174+
For example, given the following swift source file:
175+
```swift
176+
177+
public func publicFunction() { }
178+
179+
func internalFunction() { }
180+
181+
private func privateFunction() { }
182+
183+
public class PublicClass {
184+
public func publicMethod() { }
185+
186+
open func openMethod() { }
187+
188+
func internalMethod() { }
189+
}
190+
191+
internal class InternalClass {
192+
private func privateMethod() { }
193+
}
194+
```
195+
196+
Then the generated documentation will include the function `publicFunction()` and the class `PublicClass`.
197+
For the documentation of `PublicClass`,
198+
it will only include the methods `publicMethod()` and `openMethod()`.
199+
200+
* `internal`.
201+
This will include all symbols which are declared `public`, `open`, and `internal`.
202+
So in the example above,
203+
it will additionally include the function `internalFunction()` and the class `InternalClass`.
204+
But for the documentation of `InternalClass`, it will not include the method `privateMethod()`.
205+
206+
* `private`.
207+
This will also include all symbols which are declared `private` and `fileprivate`
208+
and effectively include symbols.
209+
210+
# Next: Understanding documentation comments
211+
212+
Now you know which symbols appear in the generated documentation.
213+
[Continue with the guide to understand how to write documentation comments in your source code
214+
to make the best of your documentation](02-documentation-format.md).

0 commit comments

Comments
 (0)