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 b335ca0

Browse files
Add a user guide.
1 parent 76175f5 commit b335ca0

File tree

6 files changed

+588
-0
lines changed

6 files changed

+588
-0
lines changed

‎Docs/00-introduction.md

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

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

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