Reimplement base URL support without <base> tag

Changelog.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added `--base-url` option.
-  #65 by @kean.
+  #65 by @kean and #93 by @mattt.
 - Added asset pipeline for CSS assets.
   #49 by @kaishin.
 - Add `swift-doc` version number to command and generated output.

README.md

@@ -69,7 +69,7 @@ $ make install
 
     OVERVIEW: Generates Swift documentation
 
-    USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>]
+    USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>] [--base-url <base-url>]
 
     ARGUMENTS:
       <inputs>                One or more paths to Swift files 
@@ -80,6 +80,8 @@ $ make install
       -o, --output <output>   The path for generated output (default:
                               .build/documentation)
       -f, --format <format>   The output format (default: commonmark)
+      --base-url <base-url>   The base URL used for all relative URLs in generated
+                              documents. (default: /)
       -h, --help              Show help information.
 
 The `generate` subcommand 

Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift

@@ -15,10 +15,6 @@ extension Symbol {
         node.height = 0.5
         node.fixedSize = .shape
 
-        if !(api is Unknown) {
-            node.href = "/" + path(for: self)
-        }
-
         switch api {
         case let `class` as Class:
             node.class = "class"
@@ -40,7 +36,7 @@ extension Symbol {
         return node
     }
 
-    func graph(in module: Module) -> Graph {
+    func graph(in module: Module, baseURL: String) -> Graph {
         var graph = Graph(directed: true)
 
         let relationships = module.interface.relationships.filter {
@@ -49,6 +45,11 @@ extension Symbol {
         }
 
         var symbolNode = self.node
+
+        if !(api is Unknown) {
+            symbolNode.href = path(for: self, with: baseURL)
+        }
+
         symbolNode.strokeWidth = 3.0
         symbolNode.class = [symbolNode.class, "current"].compactMap { $0 }.joined(separator: " ")
 

Sources/swift-doc/Subcommands/Generate.swift

@@ -43,6 +43,7 @@ extension SwiftDoc {
 
     func run() throws {
       let module = try Module(name: options.moduleName, paths: options.inputs)
+      let baseURL = options.baseURL
 
       let outputDirectoryURL = URL(fileURLWithPath: options.output)
       try fileManager.createDirectory(at: outputDirectoryURL, withIntermediateDirectories: true, attributes: fileAttributes)
@@ -56,9 +57,9 @@ extension SwiftDoc {
         for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) {
           switch symbol.api {
           case is Class, is Enumeration, is Structure, is Protocol:
-            pages[path(for: symbol)] = TypePage(module: module, symbol: symbol)
+            pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL)
           case let `typealias` as Typealias:
-            pages[path(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol)
+            pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL)
           case let function as Function where !function.isOperator:
             globals[function.name, default: []] += [symbol]
           case let variable as Variable:
@@ -69,7 +70,7 @@ extension SwiftDoc {
         }
 
         for (name, symbols) in globals {
-          pages[path(for: name)] = GlobalPage(module: module, name: name, symbols: symbols)
+            pages[route(for: name)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL)
         }
 
         guard !pages.isEmpty else {
@@ -87,15 +88,15 @@ extension SwiftDoc {
           }
 
           let url = outputDirectoryURL.appendingPathComponent(filename)
-          try page.write(to: url, format: format, baseURL: options.baseURL)
+          try page.write(to: url, format: format)
         } else {
           switch format {
           case .commonmark:
-            pages["Home"] = HomePage(module: module)
-            pages["_Sidebar"] = SidebarPage(module: module)
-            pages["_Footer"] = FooterPage()
+            pages["Home"] = HomePage(module: module, baseURL: baseURL)
+            pages["_Sidebar"] = SidebarPage(module: module, baseURL: baseURL)
+            pages["_Footer"] = FooterPage(baseURL: baseURL)
           case .html:
-            pages["Home"] = HomePage(module: module)
+            pages["Home"] = HomePage(module: module, baseURL: baseURL)
           }
 
           try pages.map { $0 }.parallelForEach {
@@ -110,7 +111,7 @@ extension SwiftDoc {
             }
 
             let url = outputDirectoryURL.appendingPathComponent(filename)
-            try $0.value.write(to: url, format: format, baseURL: options.baseURL)
+            try $0.value.write(to: url, format: format)
           }
         }
 

Sources/swift-doc/Supporting Types/Components/Abstract.swift

@@ -6,9 +6,11 @@ import HypertextLiteral
 
 struct Abstract: Component {
     var symbol: Symbol
+    let baseURL: String
 
-    init(for symbol: Symbol) {
+    init(for symbol: Symbol, baseURL: String) {
         self.symbol = symbol
+        self.baseURL = baseURL
     }
 
     // MARK: - Component
@@ -18,7 +20,7 @@ struct Abstract: Component {
             return Fragment {
                 List.Item {
                     Paragraph {
-                        Link(urlString: path(for: symbol), text: symbol.id.description)
+                        Link(urlString: path(for: symbol, with: baseURL), text: symbol.id.description)
                         Text { ":" }
                     }
 
@@ -31,7 +33,7 @@ struct Abstract: Component {
             return Fragment {
                 List.Item {
                     Paragraph {
-                        Link(urlString: path(for: symbol), text: symbol.id.description)
+                        Link(urlString: path(for: symbol, with: baseURL), text: symbol.id.description)
                     }
                 }
             }
@@ -43,7 +45,7 @@ struct Abstract: Component {
 
         return #"""
         <dt class="\#(descriptor)">
-            <a href=\#(path(for: symbol)) title="\#(descriptor) - \#(symbol.id.description)">
+            <a href=\#(path(for: symbol, with: baseURL)) title="\#(descriptor) - \#(symbol.id.description)">
                 \#(softbreak(symbol.id.description))
             </a>
         </dt>

Sources/swift-doc/Supporting Types/Components/Declaration.swift

@@ -9,10 +9,12 @@ import Xcode
 struct Declaration: Component {
     var symbol: Symbol
     var module: Module
+    let baseURL: String
 
-    init(of symbol: Symbol, in module: Module) {
+    init(of symbol: Symbol, in module: Module, baseURL: String) {
         self.symbol = symbol
         self.module = module
+        self.baseURL = baseURL
     }
 
     // MARK: - Component
@@ -27,7 +29,7 @@ struct Declaration: Component {
 
     var html: HypertextLiteral.HTML {
         var html = try! SwiftSyntaxHighlighter.highlight(source: symbol.declaration, using: Xcode.self)
-        html = linkCodeElements(of: html, for: symbol, in: module)
+        html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
         return HTML(html)
     }
 }

Sources/swift-doc/Supporting Types/Components/Documentation.swift

@@ -10,10 +10,12 @@ import Xcode
 struct Documentation: Component {
     var symbol: Symbol
     var module: Module
+    let baseURL: String
 
-    init(for symbol: Symbol, in module: Module) {
+    init(for symbol: Symbol, in module: Module, baseURL: String) {
         self.symbol = symbol
         self.module = module
+        self.baseURL = baseURL
     }
 
     // MARK: - Component
@@ -37,10 +39,10 @@ struct Documentation: Component {
                 Fragment { "\(documentation.summary!)" }
             }
 
-            Declaration(of: symbol, in: module)
+            Declaration(of: symbol, in: module, baseURL: baseURL)
 
             ForEach(in: documentation.discussionParts) { part in
-                DiscussionPart(part, for: symbol, in: module)
+                DiscussionPart(part, for: symbol, in: module, baseURL: baseURL)
             }
 
             if !documentation.parameters.isEmpty {
@@ -83,7 +85,7 @@ struct Documentation: Component {
 
         var fragments: [HypertextLiteralConvertible] = []
 
-        fragments.append(Declaration(of: symbol, in: module))
+        fragments.append(Declaration(of: symbol, in: module, baseURL: baseURL))
 
         if let summary = documentation.summary {
             fragments.append(#"""
@@ -97,7 +99,7 @@ struct Documentation: Component {
             fragments.append(#"""
             <div class="discussion">
                 \#(documentation.discussionParts.compactMap { part -> HTML? in
-                    DiscussionPart(part, for: symbol, in: module).html
+                    DiscussionPart(part, for: symbol, in: module, baseURL: baseURL).html
                 })
             </div>
             """# as HypertextLiteral.HTML)
@@ -178,11 +180,13 @@ extension Documentation {
         var symbol: Symbol
         var module: Module
         var part: SwiftMarkup.DiscussionPart
+        let baseURL: String
 
-        init(_ part: SwiftMarkup.DiscussionPart, for symbol: Symbol, in module: Module) {
+        init(_ part: SwiftMarkup.DiscussionPart, for symbol: Symbol, in module: Module, baseURL: String) {
             self.part = part
             self.symbol = symbol
             self.module = module
+            self.baseURL = baseURL
         }
 
         // MARK: - Component
@@ -238,11 +242,11 @@ extension Documentation {
                     let source = codeBlock.literal
                 {
                     var html = try! SwiftSyntaxHighlighter.highlight(source: source, using: Xcode.self)
-                    html = linkCodeElements(of: html, for: symbol, in: module)
+                    html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
                     return HTML(html)
                 } else {
                     var html = codeBlock.render(format: .html, options: [.unsafe])
-                    html = linkCodeElements(of: html, for: symbol, in: module)
+                    html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
                     return HTML(html)
                 }
             case .heading(let heading):

Sources/swift-doc/Supporting Types/Components/Members.swift

@@ -7,6 +7,7 @@ import HypertextLiteral
 struct Members: Component {
     var symbol: Symbol
     var module: Module
+    let baseURL: String
 
     var members: [Symbol]
 
@@ -17,9 +18,11 @@ struct Members: Component {
     var methods: [Symbol]
     var genericallyConstrainedMembers: [[GenericRequirement] : [Symbol]]
 
-    init(of symbol: Symbol, in module: Module) {
+    init(of symbol: Symbol, in module: Module, baseURL: String) {
         self.symbol = symbol
         self.module = module
+        self.baseURL = baseURL
+
         self.members = module.interface.members(of: symbol).filter { $0.extension?.genericRequirements.isEmpty != false }
 
         self.typealiases = members.filter { $0.api is Typealias }
@@ -55,7 +58,7 @@ struct Members: Component {
                             Heading {
                                 Code { member.name }
                             }
-                            Documentation(for: member, in: module)
+                            Documentation(for: member, in: module, baseURL: baseURL)
                         }
                     }
                 }
@@ -72,7 +75,7 @@ struct Members: Component {
                             Section {
                                 ForEach(in: members) { member in
                                     Heading { member.name }
-                                    Documentation(for: member, in: module)
+                                    Documentation(for: member, in: module, baseURL: baseURL)
                                 }
                             }
                         }
@@ -97,7 +100,7 @@ struct Members: Component {
                             <h3>
                                 <code>\#(softbreak(member.name))</code>
                             </h3>
-                            \#(Documentation(for: member, in: module).html)
+                            \#(Documentation(for: member, in: module, baseURL: baseURL).html)
                         </div>
                         """#
                     })
@@ -117,7 +120,7 @@ struct Members: Component {
                         \#(members.map { member -> HypertextLiteral.HTML in
                             #"""
                             <h4>\#(softbreak(member.name))</h4>
-                            \#(Documentation(for: member, in: module).html)
+                            \#(Documentation(for: member, in: module, baseURL: baseURL).html)
                             """#
                         })
                     </section>

Sources/swift-doc/Supporting Types/Components/Relationships.swift

@@ -28,16 +28,18 @@ extension StringBuilder {
 struct Relationships: Component {
     var module: Module
     var symbol: Symbol
+    let baseURL: String
     var inheritedTypes: [Symbol]
 
-    init(of symbol: Symbol, in module: Module) {
+    init(of symbol: Symbol, in module: Module, baseURL: String) {
         self.module = module
         self.symbol = symbol
         self.inheritedTypes = module.interface.typesInherited(by: symbol) + module.interface.typesConformed(by: symbol)
+        self.baseURL = baseURL
     }
 
     var graphHTML: HypertextLiteral.HTML? {
-        var graph = symbol.graph(in: module)
+        var graph = symbol.graph(in: module, baseURL: baseURL)
         guard !graph.edges.isEmpty else { return nil }
 
         graph.aspectRatio = 0.125
@@ -80,7 +82,7 @@ struct Relationships: Component {
                         if type.api is Unknown {
                             return "`\(type.id)`"
                         } else {
-                            return "[`\(type.id)`](\(path(for: type)))"
+                    return "[`\(type.id)`](\(path(for: type, with: baseURL)))"
                         }
                     }.joined(separator: ", "))
                     """#
@@ -118,7 +120,7 @@ struct Relationships: Component {
                                 """#
                             } else {
                                 return #"""
-                                <dt class="\#(descriptor)"><code><a href="\#(path(for: symbol))">\#(symbol.id)</a></code></dt>
+                                <dt class="\#(descriptor)"><code><a href="\#(path(for: symbol, with: baseURL))">\#(symbol.id)</a></code></dt>
                                 <dd>\#(commonmark: symbol.documentation?.summary ?? "")</dd>
                                 """#
                             }

Sources/swift-doc/Supporting Types/Components/Requirements.swift

@@ -7,10 +7,12 @@ import HypertextLiteral
 struct Requirements: Component {
     var symbol: Symbol
     var module: Module
+    let baseURL: String
 
-    init(of symbol: Symbol, in module: Module) {
+    init(of symbol: Symbol, in module: Module, baseURL: String) {
         self.symbol = symbol
         self.module = module
+        self.baseURL = baseURL
     }
 
     var sections: [(title: String, requirements: [Symbol])] {
@@ -31,7 +33,7 @@ struct Requirements: Component {
                     Heading { section.title }
                     ForEach(in: section.requirements) { requirement in
                         Heading { requirement.name }
-                        Documentation(for: requirement, in: module)
+                        Documentation(for: requirement, in: module, baseURL: baseURL)
                     }
                 }
             }
@@ -53,7 +55,7 @@ struct Requirements: Component {
                             <h3>
                                 <code>\#(softbreak(member.name))</code>
                             </h3>
-                            \#(Documentation(for: member, in: module).html)
+                            \#(Documentation(for: member, in: module, baseURL: baseURL).html)
                         </div>
                         """#
                     })