Merge pull request #325 from tayloraswift/validate-own-docs

Validate own docs

Author: tayloraswift

.github/workflows/build.yml

@@ -0,0 +1,64 @@
+# This workflow builds the project under the “starter” configuration, namely, what you would get
+# if you ran `swift build` without any arguments. We use this to verify that we can generate the
+# documentation for Unidoc itself.
+name: documentation
+
+on:
+    push:
+        branches: [ master ]
+    pull_request:
+        branches: [ master ]
+
+jobs:
+    linux:
+        runs-on: ubuntu-24.04
+        name: Ubuntu 24.04
+        env:
+            UNIDOC_ENABLE_INDEXSTORE: "0"
+        steps:
+            #   Important! We install an Ubuntu 22.04 Swift toolchain, and not the 24.04 one
+            #   because the 24.04 toolchain for some reason is built with assertions enabled,
+            #   which causes the Swift compiler to crash when building the package.
+            -   name: Install Swift
+                uses: tayloraswift/swift-install-action@master
+                with:
+                    swift-prefix: "swift-5.10.1-release/ubuntu2204/swift-5.10.1-RELEASE"
+                    swift-id: "swift-5.10.1-RELEASE-ubuntu22.04"
+
+            #   This installs an older version of Unidoc, not the one we are testing.
+            -   name: Install Unidoc
+                uses: tayloraswift/swift-unidoc-action@master
+                with:
+                    unidoc-version: "master"
+
+            -   name: Checkout repository
+                uses: actions/checkout@v3
+
+            -   name: Build documentation
+                run: |
+                    unidoc compile -I .. \
+                    --swift-toolchain $SWIFT_INSTALLATION \
+                    --ci fail-on-errors \
+                    --package-name swift-unidoc
+
+    macos:
+        runs-on: macos-14
+        name: macOS
+        env:
+            UNIDOC_ENABLE_INDEXSTORE: "0"
+            DEVELOPER_DIR: "/Applications/Xcode_15.3.app/Contents/Developer"
+
+        steps:
+            -   name: Install Unidoc
+                uses: tayloraswift/swift-unidoc-action@master
+                with:
+                    unidoc-version: "master"
+
+            -   name: Checkout repository
+                uses: actions/checkout@v3
+
+            -   name: Build documentation
+                run: |
+                    unidoc compile -I .. \
+                    --ci fail-on-errors \
+                    --package-name swift-unidoc

.github/workflows/docs.yml

@@ -1,6 +1,5 @@
 # This workflow builds the project for production, with IndexStoreDB integration enabled.
-
-name: ci
+name: test
 
 on:
     push:

.github/workflows/ci.yml renamed to .github/workflows/test.yml

@@ -94,7 +94,7 @@ A fresh Unidoc database contains no documentation. Let’s build some now.
 
 The documentation compiler lives in this repository, and is packaged as a normal SwiftPM executable target.
 
-To invoke the compiler, run the `unidoc-build` tool and pass it the name of the package you want to build documentation for. In our case, the “package” is `swift`, which is a special name identifying the standard library itself.
+To invoke the compiler, run the `unidoc local` tool and pass it the name of the package you want to build documentation for. In our case, the “package” is `swift`, which is a special name identifying the standard library itself.
 
 @Code(file: load-standard-library.sh, title: load-standard-library.sh)
 
@@ -130,7 +130,7 @@ git clone https://github.com/apple/swift-nio
 
 **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.
 
-Next, you can try building `swift-nio` with `unidoc-build`, specifying the path to the search directory (`/swift`) with the `-I` option.
+Next, you can try building `swift-nio` with `unidoc local`, specifying the path to the search directory (`/swift`) with the `-I` option.
 
 @Code(file: load-swift-nio.sh, title: load-swift-nio.sh)
 

Guides/docs.docc/Getting started.md

@@ -1,12 +1,12 @@
 # Previewing documentation locally
 
-This guide walks through how to use the `unidoc-preview` tool to preview documentation locally on macOS 14. This guide won’t make any effort to explain how Unidoc itself works, it is merely intended to demonstrate how to preview multi-package documentation as quickly as possible. For a more-detailed Linux-centric tour, see the <doc:Getting-started> guide.
+This guide walks through how to use the `unidoc preview` tool to preview documentation locally on macOS 14. This guide won’t make any effort to explain how Unidoc itself works, it is merely intended to demonstrate how to preview multi-package documentation as quickly as possible. For a more-detailed Linux-centric tour, see the <doc:Getting-started> guide.
 
 In this guide, you will:
 
 1.  Launch and initialize a `mongod` instance in a Docker container,
-2.  Build and run an instance of `unidoc-preview` on the macOS host,
-3.  Build the `unidoc-build` tool,
+2.  Build and run an instance of `unidoc preview` on the macOS host,
+3.  Build the `unidoc local` tool,
 4.  Generate documentation for the standard library, and
 5.  Generate documentation for two SwiftPM packages, one of which depends on the other.
 
@@ -44,23 +44,23 @@ docker exec -t unidoc-mongod-container /bin/mongosh --file /unidoc-rs-init.js
 ```
 
 
-## 3. Running `unidoc-preview`
+## 3. Running `unidoc preview`
 
-The `unidoc-preview` tool is an ordinary SwiftPM executable product. You can build and run it directly from your macOS host like this:
+The `unidoc preview` tool is an ordinary SwiftPM executable product. You can build and run it directly from your macOS host like this:
 
 ```bash
-swift run -c release unidoc-preview
+swift run -c release unidoc-tools preview
 ```
 
-The `unidoc-preview` tool will start a web server on [`http://localhost:8080`](http://localhost:8080).
+The `unidoc preview` tool will start a web server on [`http://localhost:8080`](http://localhost:8080).
 
 @Image(source: "Start page.png", alt: "Start page") {
->   The `unidoc-preview` start page.
+>   The `unidoc preview` start page.
 }
 
 ## 4. Generating documentation for the standard library
 
-Generate local documentation using the `unidoc-build local` subcommand. To start off, open a third terminal and generate the documentation for the standard library (`swift`).
+Generate local documentation using the `unidoc local` subcommand. To start off, open a third terminal and generate the documentation for the standard library (`swift`).
 
 @Code(file: load-standard-library.sh, title: load-standard-library.sh)
 
@@ -84,7 +84,7 @@ cd -
 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.
 
 ```bash
-swift run -c release unidoc-build local swift-collections -I ..
+swift run -c release unidoc-tools local swift-collections -I ..
 ```
 
 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).
@@ -99,7 +99,7 @@ Finally, let’s generate documentation for a package that depends on `swift-col
 cd ..
 git clone https://github.com/apple/swift-async-algorithms
 cd -
-swift run -c release unidoc-build local swift-async-algorithms -I ..
+swift run -c release unidoc-tools local swift-async-algorithms -I ..
 ```
 
 

Guides/docs.docc/Quickstart.md

@@ -1 +1 @@
-swift run -c release unidoc-build local swift
+swift run -c release unidoc-tools build local swift

Guides/docs.docc/local/load-standard-library.sh

@@ -1 +1 @@
-swift run -c release unidoc-build local swift-nio -I /swift
+swift run -c release unidoc-tools build local swift-nio -I /swift

Guides/docs.docc/local/load-swift-nio.sh

@@ -1,2 +1,2 @@
 swift --version
-swift run -c release unidoc-preview
+swift run -c release unidoc-tools preview

Guides/docs.docc/local/start-server.sh

@@ -2,7 +2,9 @@
 
 <strong><em><code>unidoc</code></em></strong>
 
-[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/ci.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/ci.yml)
+[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/test.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/test.yml)
+[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/docs.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/docs.yml)
+[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/package.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/package.yml)
 
 </div>
 

README.md

@@ -6,7 +6,7 @@ extension GitHub
     ///
     /// >   Note:
     /// This type would be named `GitHub.OAuthApp`, but then ``GitHub.App`` would have to be
-    /// named ``GitHub.AppApp``, and that would just be stupid.
+    /// named `GitHub.AppApp`, and that would just be stupid.
     @frozen public
     struct OAuth:GitHubApplication
     {