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

Commit 947c508

Browse files
Lukas-StuehrkLukas-Stuehrk
committed
Add a user guide.
1 parent 75108dd commit 947c508

6 files changed

+499
-0
lines changed

‎Docs/00-introduction.md

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

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

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

‎Docs/01-github-action.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Building documentation via the GitHub Action
2+
3+
We assume that you already have a
4+
[basic knowledge of GitHub actions](https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions)
5+
and understand how they work.
6+
7+
## Creating documentation with a GitHub action
8+
9+
Let's create a GitHub action which first checks out the source code of your project and then it builds the documentation
10+
for your Project. We assume that your awesome project has its Swift source files at the path `Sources/AwesomeProject` in
11+
your repository.
12+
13+
Add the file `.github/workflows/documentation.yml` to your repository:
14+
15+
# Setting a
16+
```yaml
17+
name: Documentation
18+
19+
on:
20+
push:
21+
branches:
22+
- main
23+
paths:
24+
- .github/workflows/documentation.yml
25+
- Sources/AwesomeProject/**.swift
26+
27+
jobs:
28+
build:
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- name: Checkout
33+
uses: actions/checkout@v1
34+
- name: Generate Documentation
35+
uses: SwiftDocOrg/swift-doc@master
36+
with:
37+
inputs: "Sources/SwiftDoc"
38+
output: "Documentation"
39+
```
40+
41+
Then the next time you push a commit to your `main` branch, the workflow is triggered and builds the documentation.
42+
43+
Now, building the documentation is already the first step. But very likely you also want to publish the generated
44+
documentation somewhere. That's why we also provide another GitHub action to automatically upload your documentation
45+
to your project's [GitHub Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis).
46+
47+
### Automatically upload the generated documentation to your project's GitHub wiki.
48+
49+
The [Github Wiki Publish Action](https://github.com/SwiftDocOrg/github-wiki-publish-action) publishes the contents of a
50+
directory to your project's wiki from a GitHub action workflow and is the ideal addition to the `swift-doc` action.
51+
52+
We will extend the example from above and check out the project's source code in a first step, then build the
53+
documentation in a second step and then upload the created documentation to your project's wiki in a third step.
54+
55+
```yaml
56+
57+
name: Documentation
58+
59+
on:
60+
push:
61+
branches:
62+
- main
63+
paths:
64+
- .github/workflows/documentation.yml
65+
- Sources/SwiftDoc/**.swift
66+
67+
jobs:
68+
build:
69+
runs-on: ubuntu-latest
70+
71+
steps:
72+
- name: Checkout
73+
uses: actions/checkout@v1
74+
- name: Generate Documentation
75+
uses: SwiftDocOrg/swift-doc@master
76+
with:
77+
inputs: "Sources/SwiftDoc"
78+
output: "Documentation"
79+
- name: Upload Documentation to Wiki
80+
uses: SwiftDocOrg/github-wiki-publish-action@v1
81+
with:
82+
path: "Documentation"
83+
env:
84+
GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
85+
```
86+
87+
## Choose which symbols are included by setting the access level
88+
89+
You might have noticed that the generated documentation contained less symbols that your library actually has. This is
90+
because `swift-doc` only includes public symbols by default — as this are also the symbols which are exposed to users
91+
of your library.
92+
93+
But if you want to generate documentation for apps and not only for library, or if you want to generate a documentation
94+
for developers and not only end users of your library, then you might want to include additional symbols.
95+
96+
Therefore `swift-doc` also provides the possibility to decide which symbols are included by setting the minimum access
97+
level from which symbols should be included. This is done via the optional `minimum-access-level` argument. Its possible
98+
values are:
99+
100+
* `public` (default). This will only include symbols which are declared `public` or `open`. For example, given the
101+
following swift source file:
102+
```swift
103+
104+
public func publicFunction() { }
105+
106+
func internalFunction() { }
107+
108+
private func privateFunction() { }
109+
110+
public class PublicClass {
111+
public func publicMethod() { }
112+
113+
open func openMethod() { }
114+
115+
func internalMethod() { }
116+
}
117+
118+
internal class InternalClass {
119+
private func privateMethod() { }
120+
}
121+
```
122+
123+
Then the generated documentation will include the function `publicFunction()` and the class `PublicClass`. For the
124+
documentation of `PublicClass`, it will only include the methods `publicMethod()` and `openMethod()`.
125+
126+
* `internal`. This will include all symbols which are declared `public`, `open`, and `internal`. So in the example
127+
above, it will additionally include the function `internalFunction()` and the class `InternalClass`. But for the
128+
documentation of `InternalClass`, it will not include the method `privateMethod()`.
129+
130+
## Next: Understand documentation comments
131+
132+
Now you know which symbols appear in the generated documentation. [Continue with the guide to
133+
understand how to write documentation comments in your source code to make the best of your documentation](02-documentation-format.md).

‎Docs/01-setup-swift-doc.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Setup swift-doc
2+
3+
Let's get started by setting up `swift-doc` to build documentation for your project. There are two different ways how
4+
you can use swift-doc to create documentation for your project:
5+
- If your project is hosted on GitHub, you can use swift-docs' **GitHub action** to build the documentation in a
6+
GitHub action workflow.
7+
8+
[Please follow the guide for setting up the GitHub action then.](01-github-action.md)
9+
10+
- Run swift-doc as **command-line tool** on your local machine or in your build pipeline.
11+
12+
[Please follow the guide for using the command-line then.](01-command-line-tool.md)

0 commit comments

Comments
 (0)