Merge pull request #350 from tayloraswift/simplify-cli

Simplify cli

Author: tayloraswift

Guides/docs.docc/Getting started.md

@@ -11,7 +11,23 @@ You need to have [Docker](https://www.docker.com/) installed on your development
 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.
 
 
-## Setting up a local database
+## Installing Unidoc
+
+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.
+
+
+## Setting up a local database automatically 
+
+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.
+
+@Code(file: init-server.sh, title: init-server.sh)
+
+
+## Setting up a local database manually
+
+>   Note:
+>   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.
+
 
 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.
 
@@ -49,7 +65,7 @@ This file:
 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`.
 
 
-## Initializing the database
+### Initializing the database
 
 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.
 
@@ -62,24 +78,13 @@ docker exec -t unidoc-mongod-container /bin/mongosh --file /unidoc-rs-init.js
 This only needs to be done **once** per deployment lifecycle. (For example, after clearing the `.mongod` data directory.)
 
 
-### Connecting to the database
+## Connecting to the database
 
-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.
+Once you have a `unidoc-mongod-container` running in the background, you can start a documentation server by running `unidoc preview`.
 
 @Code(file: start-server.sh, title: start-server.sh)
 
 
-### Generating certificates
-
-#### Unidoc < 0.17.0
-
-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.
-
-#### Unidoc ≥ 0.17.0
-
-You do not need to generate certificates, as Unidoc 0.17.0 can run locally in insecure mode.
-
-
 ## Populating a local documentation server
 
 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...
 Successfully uploaded symbol graph!
 ```
 
-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).
+You can view the docs by navigating to [`localhost:8080/docs/swift`](http://localhost:8080/docs/swift).
 
 >   Note:
     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.
 
 
 ### Building documentation for a local project
 
-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.
+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.
 
-Let’s try building documentation for [`swift-nio`](https://github.com/apple/swift-nio). First, we need to clone the repository.
+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.
 
 ```bash
 cd /swift
 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 local`, 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 project (`/swift/swift-nio`) with the `-i` option.
 
 @Code(file: load-swift-nio.sh, title: load-swift-nio.sh)
 

Guides/docs.docc/Quickstart.md

@@ -90,18 +90,24 @@ You should be able to view the symbol graph and its documentation at [`http://lo
 
 ## 5. Generating documentation for SwiftPM packages
 
-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.
+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.
 
 ```bash
-cd ..
 git clone https://github.com/apple/swift-collections
-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.
+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.
 
 ```bash
-unidoc local swift-collections -I ..
+unidoc local -i swift-collections
+```
+
+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.
+
+```bash
+cd swift-collections
+unidoc local
+cd -
 ```
 
 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
 >   The `swift-collections` documentation.
 }
 
-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.
+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`.
 
 ```bash
-cd ..
 git clone https://github.com/apple/swift-async-algorithms
-cd -
-unidoc local swift-async-algorithms -I ..
+unidoc local -i swift-async-algorithms
 ```
 
 

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

@@ -0,0 +1,2 @@
+swift --version
+swift run -c release unidoc init ~/unidoc

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

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

Guides/docs.docc/local/unidoc-install.sh

@@ -1,5 +1,5 @@
 UNIDOC_MIRROR=https://static.swiftinit.org/unidoc
-UNIDOC_VERSION=0.19.4
+UNIDOC_VERSION=0.19.6
 UNIDOC_PLATFORM=macOS-ARM64
 
 curl -L $UNIDOC_MIRROR/$UNIDOC_VERSION/$UNIDOC_PLATFORM/unidoc.tar.gz \

Package.resolved

@@ -102,8 +102,9 @@ let package:Package = .init(
         .package(url: "https://github.com/tayloraswift/swift-png", .upToNextMinor(
             from: "4.4.3")),
 
-        .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(
-            from: "1.5.0")),
+        // .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(
+        //     from: "1.5.0")),
+        .package(url: "https://github.com/apple/swift-argument-parser", branch: "main"),
         .package(url: "https://github.com/apple/swift-atomics", .upToNextMinor(
             from: "1.2.0")),
         .package(url: "https://github.com/apple/swift-collections", .upToNextMinor(

Package.swift

@@ -31,7 +31,9 @@ extension SSGC
 
         @Option(
             name: [.customLong("search-path"), .customShort("I")],
-            help: "Where to look for a SwiftPM package to build, if building locally",
+            help: """
+            DEPRECATED: Where to look for a SwiftPM package to build, if building locally
+            """,
             completion: .directory)
         var search:FilePath.Directory? = nil
 
@@ -67,13 +69,19 @@ extension SSGC
             help: "Run in CI mode under the specified validation level")
         var ci:ValidationBehavior? = nil
 
+        @Option(
+            name: [.customLong("project-path"), .customShort("p")],
+            help: "Path to a local project to build",
+            completion: .directory)
+        var projectPath:FilePath.Directory?
+
         @Option(
             name: [.customLong("package-name"), .customShort("n")],
             help: """
                 The symbolic name of the project to build — \
                 this is not the name specified in the `Package.swift` manifest!
                 """)
-        var project:String
+        var project:String?
 
         @Option(
             name: [.customLong("project-type"), .customShort("b")],
@@ -240,10 +248,11 @@ extension SSGC.Compile
 
         let object:SymbolGraphObject<Void>
 
-        if  let repo:String = self.repo,
+        if  let project:String = self.project,
+            let repo:String = self.repo,
             let ref:String = self.ref
         {
-            let symbol:Symbol.Package = .init(self.project)
+            let symbol:Symbol.Package = .init(project)
 
             defer
             {
@@ -277,10 +286,39 @@ extension SSGC.Compile
                 logger: logger,
                 clean: self.cleanArtifacts)
         }
-        else if
-            let search:FilePath.Directory = self.search
+        else if case "swift"? = self.project
+        {
+            object = try workspace.build(some: SSGC.StandardLibraryBuild.swift,
+                toolchain: toolchain,
+                status: status,
+                logger: logger,
+                clean: self.cleanArtifacts)
+        }
+        else
         {
-            let build:SSGC.PackageBuild = .local(project: search / self.project,
+            let computedPath:FilePath.Directory
+
+            if  let projectPath:FilePath.Directory = self.projectPath
+            {
+                computedPath = projectPath
+            }
+            else if  
+                let search:FilePath.Directory = self.search, 
+                let name:String = self.project
+            {
+                print("""
+                    Warning: '--search-path' is deprecated, use '--project-path' with the 
+                    full path to the project root instead
+                    """)
+
+                computedPath = search / name
+            }
+            else
+            {
+                throw SSGC.ProjectPathRequiredError.init()
+            }
+
+            let build:SSGC.PackageBuild = .local(project: computedPath,
                 using: ".build.ssgc",
                 as: self.type)
 
@@ -298,18 +336,6 @@ extension SSGC.Compile
                 logger: logger,
                 clean: self.cleanArtifacts)
         }
-        else if self.project == "swift"
-        {
-            object = try workspace.build(some: SSGC.StandardLibraryBuild.swift,
-                toolchain: toolchain,
-                status: status,
-                logger: logger,
-                clean: self.cleanArtifacts)
-        }
-        else
-        {
-            throw SSGC.SearchPathRequiredError.init()
-        }
 
         let output:FilePath = self.output ?? workspace.location / "docs.bson"
         try output.open(.writeOnly,

Sources/SymbolGraphBuilder/SSGC.Compile.swift

@@ -0,0 +1,6 @@
+extension SSGC
+{
+    struct ProjectPathRequiredError:Error
+    {
+    }
+}

Sources/SymbolGraphBuilder/SSGC.ProjectPathRequiredError.swift

@@ -279,13 +279,13 @@ extension Unidoc.Client<HTTP.Client2>
     }
 
     public
-    func buildAndUpload(local name:String,
-        search:FilePath.Directory?,
+    func buildAndUpload(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws
     {
-        let object:SymbolGraphObject<Void> = try await self.build(local: name,
-            search: search,
+        let object:SymbolGraphObject<Void> = try await self.build(local: local,
+            name: name,
             type: type,
             with: toolchain)
 
@@ -301,13 +301,13 @@ extension Unidoc.Client<HTTP.Client2>
 extension Unidoc.Client<HTTP.Client1>
 {
     public
-    func buildAndUpload(local name:String,
-        search:FilePath.Directory?,
+    func buildAndUpload(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws
     {
-        let object:SymbolGraphObject<Void> = try await self.build(local: name,
-            search: search,
+        let object:SymbolGraphObject<Void> = try await self.build(local: local,
+            name: name,
             type: type,
             with: toolchain)
 
@@ -318,13 +318,13 @@ extension Unidoc.Client<HTTP.Client1>
             http://\(self.http.remote):\(self.port)/tags/\(object.metadata.package.id)
             """)
     }
-}
+} 
 extension Unidoc.Client
 {
     /// Name is case-sensitive, so it is not modeled as a ``Symbol.Package``.
     private
-    func build(local name:String,
-        search:FilePath.Directory?,
+    func build(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws -> SymbolGraphObject<Void>
     {
@@ -334,7 +334,6 @@ extension Unidoc.Client
         var arguments:[String] = [
             "compile",
 
-            "--package-name", "\(name)",
             "--project-type", "\(type)",
             "--workspace", "\(workspace.location)",
             "--output", "\(docs)",
@@ -354,10 +353,15 @@ extension Unidoc.Client
             arguments.append("--sdk")
             arguments.append("\(sdk)")
         }
-        if  let search:FilePath.Directory
+        if  let local:FilePath.Directory 
+        {
+            arguments.append("--project-path")
+            arguments.append("\(local)")
+        }
+        if  let name:String
         {
-            arguments.append("--search-path")
-            arguments.append("\(search)")
+            arguments.append("--package-name")
+            arguments.append("\(name)")
         }
 
         let ssgc:SystemProcess = try .init(command: self.executablePath, arguments: arguments)