Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings
This repository was archived by the owner on Jun 1, 2023. It is now read-only.

Commit 947c508

Browse files
Add a user guide.
1 parent 75108dd commit 947c508

File tree

6 files changed

+499
-0
lines changed

6 files changed

+499
-0
lines changed

‎Docs/00-introduction.md

Lines changed: 41 additions & 0 deletions
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

Lines changed: 169 additions & 0 deletions
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

Lines changed: 133 additions & 0 deletions
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

Lines changed: 12 additions & 0 deletions
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)

AltStyle によって変換されたページ (->オリジナル) /