You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Guides/docs.docc/Getting started.md
+24-21Lines changed: 24 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,23 @@ You need to have [Docker](https://www.docker.com/) installed on your development
11
11
It is theoretically possible to run Unidoc without Docker, but Docker makes it much easier to do so, because you will not need to (directly) manage a local [MongoDB](https://mongodb.com) deployment.
12
12
13
13
14
-
## Setting up a local database
14
+
## Installing Unidoc
15
+
16
+
The examples in this tutorial assume you are building Unidoc from source. However, you can also download [pre-built binaries](/Quickstart) for a select set of platforms.
17
+
18
+
19
+
## Setting up a local database automatically
20
+
21
+
Unidoc can set up a `mongod` instance for you automatically through the `unidoc init` command. This tool takes a directory path as an argument, which it uses to persist the state of the database. In the example below, we will create the documentation database in a directory named `unidoc` in your home directory.
> The steps in this section are provided for educational purposes, to help you understand how Unidoc works. If you have set up the database automatically, you can skip this section.
30
+
15
31
16
32
A Unidoc server is a server that talks to a second server, a MongoDB server. Therefore, before you can start a Unidoc server, you need to set up and launch a local [MongoDB](https://github.com/tayloraswift/swift-mongodb) deployment.
17
33
@@ -49,7 +65,7 @@ This file:
49
65
The `unidoc-test` network is helpful for testing, but for the purposes of this tutorial, you will mostly be accessing the `mongod` process through `localhost:27017`.
50
66
51
67
52
-
## Initializing the database
68
+
###Initializing the database
53
69
54
70
The mongod instance will create a `.mongod` directory at the root of the cloned repository. This directory contains the state of the deployment, and like all database deployments, it can outlive the mongod process. This means you can kill (or crash) the mongod instance but it will not lose data unless you clear or delete its data directory.
This only needs to be done **once** per deployment lifecycle. (For example, after clearing the `.mongod` data directory.)
63
79
64
80
65
-
###Connecting to the database
81
+
## Connecting to the database
66
82
67
-
Once you have a `unidoc-mongod-container` running in the background, you can start a documentation server. There are many ways to run a documentation server, but if you are developing in a Docker container, the easiest way is compile Unidoc and run the server as a normal process.
83
+
Once you have a `unidoc-mongod-container` running in the background, you can start a documentation server by running `unidoc preview`.
If you are starting the server for the first time, you likely need to populate the `Assets/certificates/` directory with TLS certificates. See <doc:GeneratingCertificates> for instructions on how to do this.
77
-
78
-
#### Unidoc ≥ 0.17.0
79
-
80
-
You do not need to generate certificates, as Unidoc 0.17.0 can run locally in insecure mode.
81
-
82
-
83
88
## Populating a local documentation server
84
89
85
90
If you did all of the previous steps correctly, you should be able to navigate to [`localhost:8080/`](http://localhost:8080/) and view a blank homepage.
@@ -111,26 +116,24 @@ Uploading symbol graph...
111
116
Successfully uploaded symbol graph!
112
117
```
113
118
114
-
Because you built these docs “abnormally” (meaning: not from a GitHub repository), they won’t show up in the homepage, but you can view them by navigating directly to [`localhost:8080/docs/swift`](http://localhost:8080/docs/swift).
119
+
You can view the docs by navigating to [`localhost:8080/docs/swift`](http://localhost:8080/docs/swift).
115
120
116
121
> Note:
117
122
You may see a lot of compiler errors when building the standard library. This is expected, as the documentation for the standard library contains many errors.
118
123
119
124
120
125
### Building documentation for a local project
121
126
122
-
Building documentation for a local project is similar to building documentation for the standard library, except you need to provide a path to a directory containing the project.
127
+
Building documentation for a local project is similar to building documentation for the standard library, except you need to provide a path to the project directory.
123
128
124
-
Let’s try building documentation for [`swift-nio`](https://github.com/apple/swift-nio). First, we need to clone the repository.
129
+
Let’s try building documentation for [`swift-nio`](https://github.com/apple/swift-nio). First, let’s clone the repository to a directory in `/swift`, which is a plausible place to store Git repositories in a devcontainer.
125
130
126
131
```bash
127
132
cd /swift
128
133
git clone https://github.com/apple/swift-nio
129
134
```
130
135
131
-
**Where** you clone the repository is important, because you will need to tell Unidoc where to find the project. In this example, we cloned the repository inside a directory called `/swift`, which is a plausible place to store Git repositories in a devcontainer.
132
-
133
-
Next, you can try building `swift-nio` with `unidoc local`, specifying the path to the search directory (`/swift`) with the `-I` option.
136
+
Next, you can try building `swift-nio` with `unidoc local`, specifying the path to the project (`/swift/swift-nio`) with the `-i` option.
Copy file name to clipboardExpand all lines: Guides/docs.docc/Quickstart.md
+13-9Lines changed: 13 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -90,18 +90,24 @@ You should be able to view the symbol graph and its documentation at [`http://lo
90
90
91
91
## 5. Generating documentation for SwiftPM packages
92
92
93
-
Now, let’s generate documentation for [swift-collections](https://github.com/apple/swift-collections), a popular SwiftPM package. Download the library’s source code to a sibling directory.
93
+
Now, let’s generate documentation for [swift-collections](https://github.com/apple/swift-collections), a popular SwiftPM package. Download the library’s source code using Git.
Generating documentation for a package is similar to generating documentation for the standard library, except you need to specify a search path to a directory containing the project. Because you downloaded the `swift-collections` repository to a sibling directory, you can use `..` for the search path.
99
+
To generate documentation for a package, you need to tell Unidoc where to find the project. Because you downloaded the `swift-collections` repository to a child directory, you can use `-i swift-collections` for the project path.
102
100
103
101
```bash
104
-
unidoc local swift-collections -I ..
102
+
unidoc local -i swift-collections
103
+
```
104
+
105
+
The default value for the project path is the current working directory (`.`), so alternatively, you could navigate to the `swift-collections` directory and run `unidoc local` without any arguments.
106
+
107
+
```bash
108
+
cd swift-collections
109
+
unidoc local
110
+
cd -
105
111
```
106
112
107
113
You should be able to view the symbol graph and its documentation at [`http://localhost:8080/tags/swift-collections`](http://localhost:8080/tags/swift-collections).
@@ -110,13 +116,11 @@ You should be able to view the symbol graph and its documentation at [`http://lo
110
116
> The `swift-collections` documentation.
111
117
}
112
118
113
-
Finally, let’s generate documentation for a package that depends on `swift-collections`. Download the source code for [swift-async-algorithms](https://github.com/apple/swift-async-algorithms) to another sibling directory.
119
+
Finally, let’s generate documentation for a package that depends on `swift-collections`. Download the source code for [swift-async-algorithms](https://github.com/apple/swift-async-algorithms) to a sibling directory of `swift-collections`.
0 commit comments