Add servedocc example

Has error checking and everything ;-)

Author: helje5

Package.swift

@@ -14,6 +14,7 @@ let package = Package(
     .executable(name: "httpd-helloworld", targets: [ "httpd-helloworld" ]),
     .executable(name: "connect-static",   targets: [ "connect-static"   ]),
     .executable(name: "express-simple",   targets: [ "express-simple"   ]),
+    .executable(name: "servedocc",        targets: [ "servedocc"        ]),
     .executable(name: "todomvc",          targets: [ "todomvc"          ]),
     .executable(name    :   "express-simple-lambda",
                 targets : [ "express-simple-lambda" ])
@@ -36,6 +37,7 @@ let package = Package(
     .target(name: "httpd-helloworld", dependencies: [ "Macro"        ]),
     .target(name: "connect-static",   dependencies: [ "MacroExpress" ]),
     .target(name: "express-simple",   dependencies: [ "MacroExpress", "cows" ]),
+    .target(name: "servedocc",        dependencies: [ "MacroExpress" ]),
     .target(name: "todomvc",          dependencies: [ "MacroExpress" ]),
 
     .target(name: "express-simple-lambda",

README.md

@@ -173,6 +173,19 @@ $ swift run todomvc
 2020-06-03T14:58:59+0200 notice: Server listening on http://localhost:1337
 ```
 
+### [servedocc](Sources/servedocc/)
+
+Macro server to serve "DocC" archives, a format to document Swift frameworks
+and packages:
+[Documenting a Swift Framework or Package](https://developer.apple.com/documentation/Xcode/documenting-a-swift-framework-or-package).
+
+```bash
+$ swift run servedocc SlothCreator.doccarchive
+2021-06-26T17:14:08+0200 notice μ.console : Server listening on: http://localhost:1337/
+2021-06-26T17:14:08+0200 notice μ.console : DocC Archive: /Users/helge/Downloads/SlothCreator.doccarchive
+2021-06-26T17:14:13+0200 notice μ.console : GET /documentation/              200 - - 2   ms
+```
+
 
 ## Who
 

Sources/servedocc/README.md

@@ -0,0 +1,43 @@
+<h2>Macro.swift servedocc
+  <img src="http://zeezide.com/img/macro/MacroExpressIcon128.png"
+           align="right" width="100" height="100" />
+</h2>
+
+Macro server to serve "DocC" archives, a format to document Swift frameworks
+and packages:
+[Documenting a Swift Framework or Package](https://developer.apple.com/documentation/Xcode/documenting-a-swift-framework-or-package).
+
+*Note*: This is for serving an exported documentation archive (`.doccarchive`),
+not for building documentation from a DocC catalog.
+
+## Usage
+
+The server can be either run as a
+[swift-sh](https://github.com/mxcl/swift-sh) script
+(install using a simple `brew install mxcl/made/swift-sh`),
+from within Xcode or via `swift run`.
+
+### Via swift-sh
+
+Example:
+```bash
+$ cd Sources/servedocc
+$ ./main.swift ~/Downloads/SlothCreator.doccarchive
+```
+
+
+### Who
+
+**Macro** is brought to you by
+the
+[Always Right Institute](http://www.alwaysrightinstitute.com)
+and
+[ZeeZide](http://zeezide.de).
+We like 
+[feedback](https://twitter.com/ar_institute), 
+GitHub stars, 
+cool [contract work](http://zeezide.com/en/services/services.html),
+presumably any form of praise you can think of.
+
+There is a `#microexpress` channel on the 
+[Noze.io Slack](http://slack.noze.io/). Feel free to join!

Sources/servedocc/main.swift

@@ -0,0 +1,94 @@
+#!/usr/bin/swift sh
+
+import MacroExpress // @Macro-swift
+
+
+// MARK: - Parse Commandline Arguments & Usage
+
+func usage() {
+  let tool = path.basename(process.argv.first ?? "servedocc")
+  print(
+    """
+    Usage: \(tool) <docc archive folder>
+    
+    Example:
+    
+      \(tool) SlothCreator.doccarchive
+    
+    """
+  )
+}
+
+guard process.argv.count == 2 else {
+  usage()
+  process.exit(1)
+}
+
+let archivePath = process.argv[1]
+let indexPath   = archivePath + "/index.html"
+let docPath     = archivePath + "/data/documentation"
+
+guard fs.existsSync(archivePath) else {
+  print("Specified file does not exist:", archivePath)
+  process.exit(2)
+}
+guard fs.existsSync(indexPath), fs.existsSync(docPath) else {
+  print("File does not look like a DocC archive:", archivePath)
+  process.exit(3)
+}
+
+guard let dataIndex = (try? fs.readdirSync(docPath))?
+                              .first(where: { $0.hasSuffix(".json")} )
+else {
+  print("File does not look like a DocC archive, missing data index:",
+        archivePath)
+  process.exit(3)
+}
+let dataIndexPath = docPath + "/" + dataIndex
+
+
+// MARK: - Serve Individual
+
+/// This serves individual, fixed files.
+func serveFile(_ path: String) -> Middleware {
+  return { req, res, next in
+    fs.createReadStream(path)
+      .pipe(res)
+      .onError { error in
+        console.error("Failed to serve \(path):", error)
+        res.status(500)
+      }
+  }
+}
+
+
+// MARK: - Configure and Start the Server
+
+let staticDirs  = [ "css", "data", "downloads", "images", "img",
+                    "index", "js", "videos" ]
+let staticFiles = [ "favicon.ico", "favicon.svg", "theme-settings.json" ]
+
+let app = express()
+app.use(logger("dev"))
+
+// Map all matching requests to this index.html
+app.get("/documentation/*",         serveFile(indexPath))
+app.get("/tutorials/*",             serveFile(indexPath))
+app.get("/data/documentation.json", serveFile(dataIndexPath))
+
+for path in staticDirs { // serve the whole directory ("/*" match)
+  app.get("/" + path + "/*", serveStatic(archivePath))
+}
+for path in staticFiles { // just serve the specific file
+  app.get("/" + path, serveStatic(archivePath))
+}
+
+// redirects
+app.get("/tutorials")     { _, res, _ in res.redirect("/tutorials/")     }
+   .get("/documentation") { _, res, _ in res.redirect("/documentation/") }
+   .get                   { _, res, _ in res.redirect("/documentation/") }
+
+app.listen(1337) {
+  console.log("Server listening on: http://localhost:1337/")
+  console.log("DocC Archive:", archivePath)
+}