Skip to content
This repository has been archived by the owner on Jun 1, 2023. It is now read-only.

Add new parameter for date formats, and default to en_US #287

Closed
wants to merge 3 commits into from
Closed

Add new parameter for date formats, and default to en_US #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
625cc0e
Add new parameter for date formats, and default to en_US
f-meloni May 22, 2021
45b22bd
Remove not needed self
f-meloni May 23, 2021
35f9150
Split long lines
f-meloni May 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
42 changes: 33 additions & 9 deletions Sources/swift-doc/Subcommands/Generate.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ extension SwiftDoc {
@Option(name: .long,
help: "The minimum access level of the symbols included in generated documentation.")
var minimumAccessLevel: AccessLevel = .public

@Option(name: .long,
help: "The locale used to format the printed dates")
var datesLocale: String = "en_US"
}

static var configuration = CommandConfiguration(abstract: "Generates Swift documentation")
Expand All @@ -47,6 +51,8 @@ extension SwiftDoc {
var options: Options

func run() throws {
let datesLocale = Locale(identifier: options.datesLocale)

for directory in options.inputs {
var isDirectory: ObjCBool = false
if !FileManager.default.fileExists(atPath: directory, isDirectory: &isDirectory) {
Expand All @@ -72,11 +78,11 @@ extension SwiftDoc {
for symbol in module.interface.topLevelSymbols.filter(symbolFilter) {
switch symbol.api {
case is Class, is Enumeration, is Structure, is Protocol:
pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL, includingChildren: symbolFilter)
pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL, datesLocale: datesLocale, includingChildren: symbolFilter)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please avoid long lines, as with these changes it now requires horizontal scrolling to review even on a wide screen, and makes it even harder on narrow screens. This is applicable to the rest of the long lines in this diff.

Suggested change
pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL, datesLocale: datesLocale, includingChildren: symbolFilter)
pages[route(for: symbol)] = TypePage(
module: module,
symbol: symbol,
baseURL: baseURL,
datesLocale: datesLocale,
includingChildren: symbolFilter
)

Copy link
Author

@f-meloni f-meloni May 23, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be cool to some swiftformat and swiftlint config to automate the check and possibly also the formatting part :P
What do you think?
I can help to set it up if you want

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, sounds good to me! @mattt WDYT?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we are going to add linting, I would suggest that we should stick to swift-format for linting rather than using swift-lint. As to setting that up, its pretty trivial (there is an example at https://github.com/compnerd/swift-win32/blob/main/.github/workflows/lint.yml).

case let `typealias` as Typealias:
pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL)
pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL, datesLocale: datesLocale)
case is Operator:
let operatorPage = OperatorPage(module: module, symbol: symbol, baseURL: baseURL, includingImplementations: symbolFilter)
let operatorPage = OperatorPage(module: module, symbol: symbol, baseURL: baseURL, datesLocale: datesLocale, includingImplementations: symbolFilter)
if !operatorPage.implementations.isEmpty {
pages[route(for: symbol)] = operatorPage
}
Expand All @@ -97,11 +103,11 @@ extension SwiftDoc {
symbolsByExternalType[extensionDeclaration.extendedType, default: []] += [symbol]
}
for (typeName, symbols) in symbolsByExternalType {
pages[route(for: typeName)] = ExternalTypePage(module: module, externalType: typeName, symbols: symbols, baseURL: baseURL)
pages[route(for: typeName)] = ExternalTypePage(module: module, externalType: typeName, symbols: symbols, baseURL: baseURL, datesLocale: datesLocale)
}

for (name, symbols) in globals {
pages[route(for: name)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL)
pages[route(for: name)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL, datesLocale: datesLocale)
}

guard !pages.isEmpty else {
Expand All @@ -126,11 +132,29 @@ extension SwiftDoc {
} else {
switch format {
case .commonmark:
pages["Home"] = HomePage(module: module, externalTypes: Array(symbolsByExternalType.keys), baseURL: baseURL, symbolFilter: symbolFilter)
pages["_Sidebar"] = SidebarPage(module: module, externalTypes: Set(symbolsByExternalType.keys), baseURL: baseURL, symbolFilter: symbolFilter)
pages["_Footer"] = FooterPage(baseURL: baseURL)
pages["Home"] = HomePage(
module: module,
externalTypes: Array(symbolsByExternalType.keys),
baseURL: baseURL,
datesLocale: datesLocale,
symbolFilter: symbolFilter
)
pages["_Sidebar"] = SidebarPage(
module: module,
externalTypes: Set(symbolsByExternalType.keys),
baseURL: baseURL,
datesLocale: datesLocale,
symbolFilter: symbolFilter
)
pages["_Footer"] = FooterPage(baseURL: baseURL, datesLocale: datesLocale)
case .html:
pages["Home"] = HomePage(module: module, externalTypes: Array(symbolsByExternalType.keys), baseURL: baseURL, symbolFilter: symbolFilter)
pages["Home"] = HomePage(
module: module,
externalTypes: Array(symbolsByExternalType.keys),
baseURL: baseURL,
datesLocale: datesLocale,
symbolFilter: symbolFilter
)
}

try pages.map { $0 }.parallelForEach {
Expand Down
2 changes: 1 addition & 1 deletion Sources/swift-doc/Supporting Types/Layout.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ func layout(_ page: Page) -> HTML {
</main>

<footer>
\#(FooterPage(baseURL: page.baseURL).html)
\#(FooterPage(baseURL: page.baseURL, datesLocale: page.datesLocale).html)
</footer>
</body>
</html>
Expand Down
1 change: 1 addition & 0 deletions Sources/swift-doc/Supporting Types/Page.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ protocol Page: HypertextLiteralConvertible {
var title: String { get }
var document: CommonMark.Document { get }
var html: HypertextLiteral.HTML { get }
var datesLocale: Locale { get }
}

extension Page {
Expand Down
6 changes: 4 additions & 2 deletions Sources/swift-doc/Supporting Types/Pages/ExternalTypePage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ import SwiftDoc
import HypertextLiteral
import SwiftMarkup
import SwiftSemantics
import Foundation

struct ExternalTypePage: Page {

let module: Module
let externalType: String
let baseURL: String
Expand All @@ -14,11 +14,13 @@ struct ExternalTypePage: Page {
let initializers: [Symbol]
let properties: [Symbol]
let methods: [Symbol]
let datesLocale: Locale

init(module: Module, externalType: String, symbols: [Symbol], baseURL: String) {
init(module: Module, externalType: String, symbols: [Symbol], baseURL: String, datesLocale: Locale) {
self.module = module
self.externalType = externalType
self.baseURL = baseURL
self.datesLocale = datesLocale

self.typealiases = symbols.filter { $0.api is Typealias }
self.initializers = symbols.filter { $0.api is Initializer }
Expand Down
7 changes: 6 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/FooterPage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ fileprivate let dateFormatter: DateFormatter = {
var dateFormatter = DateFormatter()
dateFormatter.dateStyle = .long
dateFormatter.timeStyle = .none

return dateFormatter
}()

Expand All @@ -19,9 +20,11 @@ fileprivate let href = "https://github.com/SwiftDocOrg/swift-doc"

struct FooterPage: Page {
let baseURL: String
let datesLocale: Locale

init(baseURL: String) {
init(baseURL: String, datesLocale: Locale) {
self.baseURL = baseURL
self.datesLocale = datesLocale
}

// MARK: - Page
Expand All @@ -37,6 +40,8 @@ struct FooterPage: Page {
}

var html: HypertextLiteral.HTML {
dateFormatter.locale = datesLocale
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've also noticed that there is a discrepancy with the Markdown footer, that uses "Generated at \(timestamp) using [swift-doc](\(href)) \(SwiftDoc.configuration.version)." while it could use "Generated on \(dateString)" instead.
WDYT?


let timestamp = timestampDateFormatter.string(from: Date())
let dateString = dateFormatter.string(from: Date())

Expand Down
5 changes: 4 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/GlobalPage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,21 @@ import SwiftSemantics
import SwiftDoc
import CommonMarkBuilder
import HypertextLiteral
import Foundation

struct GlobalPage: Page {
let module: Module
let name: String
let symbols: [Symbol]
let baseURL: String
let datesLocale: Locale

init(module: Module, name: String, symbols: [Symbol], baseURL: String) {
init(module: Module, name: String, symbols: [Symbol], baseURL: String, datesLocale: Locale) {
self.module = module
self.name = name
self.symbols = symbols
self.baseURL = baseURL
self.datesLocale = datesLocale
}

// MARK: - Page
Expand Down
5 changes: 4 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/HomePage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,12 @@ import CommonMarkBuilder
import SwiftDoc
import SwiftSemantics
import HypertextLiteral
import struct Foundation.Locale

struct HomePage: Page {
var module: Module
let baseURL: String
let datesLocale: Locale

var classes: [Symbol] = []
var enumerations: [Symbol] = []
Expand All @@ -18,9 +20,10 @@ struct HomePage: Page {

let externalTypes: [String]

init(module: Module, externalTypes: [String], baseURL: String, symbolFilter: (Symbol) -> Bool) {
init(module: Module, externalTypes: [String], baseURL: String, datesLocale: Locale, symbolFilter: (Symbol) -> Bool) {
self.module = module
self.baseURL = baseURL
self.datesLocale = datesLocale

self.externalTypes = externalTypes

Expand Down
5 changes: 4 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/OperatorPage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,22 @@ import SwiftSemantics
import SwiftDoc
import CommonMarkBuilder
import HypertextLiteral
import Foundation

struct OperatorPage: Page {
let module: Module
let symbol: Symbol
let implementations: [Symbol]
let baseURL: String
let datesLocale: Locale

init(module: Module, symbol: Symbol, baseURL: String, includingImplementations symbolFilter: (Symbol) -> Bool) {
init(module: Module, symbol: Symbol, baseURL: String, datesLocale: Locale, includingImplementations symbolFilter: (Symbol) -> Bool) {
precondition(symbol.api is Operator)
self.module = module
self.symbol = symbol
self.implementations = module.interface.functionsByOperator[symbol]?.filter(symbolFilter).sorted() ?? []
self.baseURL = baseURL
self.datesLocale = datesLocale
}

// MARK: - Page
Expand Down
5 changes: 4 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import SwiftSemantics
import SwiftDoc
import CommonMarkBuilder
import HypertextLiteral
import struct Foundation.Locale
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In some files the compiler was having some issues with Protocol once Foundation was imported, also when I used SwiftSemantics.Protocol instead of just Protocol, so I've imported only Foundation.Locale where the issue was happening


struct SidebarPage: Page {
var module: Module
Expand All @@ -15,10 +16,12 @@ struct SidebarPage: Page {
var globalVariableNames: Set<String> = []

let externalTypes: Set<String>
let datesLocale: Locale

init(module: Module, externalTypes: Set<String>, baseURL: String, symbolFilter: (Symbol) -> Bool) {
init(module: Module, externalTypes: Set<String>, baseURL: String, datesLocale: Locale, symbolFilter: (Symbol) -> Bool) {
self.module = module
self.baseURL = baseURL
self.datesLocale = datesLocale

self.externalTypes = externalTypes

Expand Down
5 changes: 4 additions & 1 deletion Sources/swift-doc/Supporting Types/Pages/TypePage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,21 @@ import SwiftSemantics
import SwiftDoc
import CommonMarkBuilder
import HypertextLiteral
import Foundation

struct TypePage: Page {
let module: Module
let symbol: Symbol
let baseURL: String
let datesLocale: Locale
let symbolFilter: (Symbol) -> Bool

init(module: Module, symbol: Symbol, baseURL: String, includingChildren symbolFilter: @escaping (Symbol) -> Bool) {
init(module: Module, symbol: Symbol, baseURL: String, datesLocale: Locale, includingChildren symbolFilter: @escaping (Symbol) -> Bool) {
precondition(symbol.api is Type)
self.module = module
self.symbol = symbol
self.baseURL = baseURL
self.datesLocale = datesLocale
self.symbolFilter = symbolFilter
}

Expand Down
7 changes: 5 additions & 2 deletions Sources/swift-doc/Supporting Types/Pages/TypealiasPage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,20 @@ import SwiftSemantics
import SwiftDoc
import CommonMarkBuilder
import HypertextLiteral
import Foundation

struct TypealiasPage: Page {
let module: Module
let symbol: Symbol
let baseURL: String

init(module: Module, symbol: Symbol, baseURL: String) {
let datesLocale: Locale

init(module: Module, symbol: Symbol, baseURL: String, datesLocale: Locale) {
precondition(symbol.api is Typealias)
self.module = module
self.symbol = symbol
self.baseURL = baseURL
self.datesLocale = datesLocale
}

// MARK: - Page
Expand Down