-
Notifications
You must be signed in to change notification settings - Fork 127
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Static Hosting Support #44
Add Static Hosting Support #44
Conversation
rdar://70800606
@macdevnet I tested this out with the experimental custom header/footer support that we use for DocC's docs and realized we forgot to take that into account. @mportiz08 put that together originally so he has more context here. I put together a proposed implementation here: ethan-kusters@119770f. But I think we could take that as a follow-up PR since the header/footer support is still experimental. If you'd like to resolve it here that's fine by me as well. |
@@ -330,13 +352,20 @@ public struct ConvertAction: Action, RecreatingContext { | |||
allProblems.append(contentsOf: indexerProblems) | |||
} | |||
|
|||
// Process Static Hosting is needed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
// Process Static Hosting is needed. | |
// Process Static Hosting as needed. |
@@ -330,13 +352,20 @@ public struct ConvertAction: Action, RecreatingContext { | |||
allProblems.append(contentsOf: indexerProblems) | |||
} | |||
|
|||
// Process Static Hosting is needed. | |||
if transformForStaticHosting, let templateDirectory = htmlTemplateDirectory { | |||
let dataProvider = try LocalFileSystemDataProvider(rootURL: temporaryFolder.appendingPathComponent("data")) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We're now constructing the data directory by hand in several different places (temporaryFolder.appendingPathComponent("data")
), it'd be nice if there was a constant or computed property or something more centralized so this string and path manipulation wasn't replicated.
self.diagnosticEngine.add(DiagnosticConsoleWriter(formattingOptions: [])) | ||
} | ||
|
||
/// Converts each eligable file from the source archive, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// Converts each eligable file from the source archive, | |
/// Converts each eligible file from the source archive and |
} | ||
|
||
/// Converts each eligable file from the source archive, | ||
/// saves the results in the given output folder. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// saves the results in the given output folder. | |
/// saves the results in the given output folder. |
try setupOutputDirectory(outputURL: outputURL) | ||
|
||
// Copy the appropriate folders from the archive. | ||
// We will do it item as we want to preserve anything intentionally left in the output URL by `setupOutputDirectory` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure I follow this second sentence, especially the "We will do it item as we want" part.
} | ||
|
||
// Create a StaticHostableTransformer targeted at the archive data folder | ||
let dataProvider = try LocalFileSystemDataProvider(rootURL: rootURL.appendingPathComponent("data")) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another place where the data directory is constructed.
let htmlOutputURL = directoryRoot.appendingPathComponent(newDirectory) | ||
try createDirectory(url: htmlOutputURL) | ||
|
||
// Process the direcorty contents |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
// Process the direcorty contents | |
// Process the directory contents |
/// - directory: The relative path (to the root) of the directory for which then content will processed. | ||
/// - nodes: The directory contents | ||
/// - Returns: An array of problems that may have occured during processing | ||
private func processDirectoryContents(directoryRoot: URL, relativeSubPath: String, directoryContents: [FSNode]) throws { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For my own understanding, what are these process
methods doing, exactly? Is there a way to encapsulate this traversal behavior so it's easier to understand and more testable? For example, if these methods are used to crawl a directory and do something with each file, perhaps it'd be worth creating a type that just knows how to walk FS nodes and e.g. invoke a transformation closure or something on each file.
/// - dir: The FSNode that represents the directory | ||
/// - currentDirectory: The relative path (to the root) of the directory that will contain this directory | ||
/// - Returns: An array of problems that may have occured during processing | ||
private func processDirectory(directoryRoot: URL, currentDirectoryNode: FSNode.Directory, directorySubPath: String) throws { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, not really clear what this method is doing because it's just called "process".
if !newDirectory.isEmpty { | ||
newDirectory += "/" | ||
} | ||
newDirectory += newPathComponent |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any sort of string concatenation of paths raises alarm bells for me. I'm not 100% clear on what this method is doing, but could it use URLComponents or appendingPathComponent?
@testable import SwiftDocCUtilities | ||
|
||
class ConvertActionStaticHostableTests: StaticHostingBaseTests { | ||
/// Creates a DocC archive and then archive woth options to produce static content which is then validated. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// Creates a DocC archive and then archive woth options to produce static content which is then validated. | |
/// Creates a DocC archive and then archives it with options to produce static content which is then validated. |
let templateURL: URL = temporaryFolder.appendingPathComponent(HTMLTemplate.templateFileName.rawValue) | ||
if fileManager.fileExists(atPath: templateURL.path) { | ||
// If the `transformForStaticHosting` is not set but there is a `hostingBasePath` | ||
// then transform the index template |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure I understand this behavior. Why are we modifying the index.html
if transformForStaticHosting
is not set?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We still transform the template if hostingBasePath
has been set to allow the non static version of the archive to be hosted somewhere other than root.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change was based on some feedback we got from Konrad in the forums: https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572/7.
The hosting-base-path
parameter isn't specific to the transform-for-static-hosting
work we're doing so it makes sense to support it here as well.
@swift-ci please test |
@swift-ci please test |
`includesDirectoriesPostOrder` is not available on Linux.
@swift-ci please test |
@swift-ci please test |
Hi @jackhl! Thank you for all the great feedback here. I think we've addressed the majority of your points but I'd like to leave the pieces that require a larger refactor for a future PR. Definitely work that we should do, but I don't think it should block landing this now since the core pieces are here. I've filed SR-15575 to track addressing the remaining feedback in a future PR. |
Additionally, I've filed SR-15576 to track improving this implementation to support DocC's experimental header/footer support. Since |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you @macdevnet for all your great work here! Really excited to land this. 🥳
Relevant forums discussion: https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572. Resolves rdar://70800606. Co-authored-by: Ethan Kusters <ekusters@apple.com>
* Add Static Hosting Support (#44) Relevant forums discussion: https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572. Resolves rdar://70800606. Co-authored-by: Ethan Kusters <ekusters@apple.com> * Sort output to avoid relying on the undefined order of directory content (#57) Co-authored-by: Steve Scott (Scotty) <macdevnet@users.noreply.github.com> Co-authored-by: David Rönnqvist <ronnqvist@apple.com>
Updates swift-markdown to include: commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 5fc007220571bf194930a98edeab7133156ab01c Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 12:20:47 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (swiftlang#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (swiftlang#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (swiftlang#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Updates swift-markdown to include: commit 97df6e2812adcf8698204ca5f0756563ef36e5c1 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 7a7c59d1160fddd23e2379ec5ee8c71df7fd0b3b Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array. commit 36cf89e36e94b025dbe37d82fe2a7da3f39d4204 Author: Franklin Schrans <fschrans@apple.com> Date: Wed Mar 23 14:38:18 2022 +0100 Remove extraneous print in test (#33) commit e50693584310a9190071c96c839485b6f2376832 Author: Ethan Kusters <ekusters@apple.com> Date: Mon Mar 21 10:42:02 2022 -0700 Publish Swift Markdown's documentation to GitHub pages (#32) * Adopt the Swift-DocC Plugin for documentation generation * Add a script for publishing docs to GitHub pages * Add missing license headers * Move README docs to articles in the DocC catalog * Remove out-of-date documentation about `DiagnosticEngine` Swift markdown no longer includes a DiagnosticEngine so these links were failing to resolve. commit 5f10cfb030f43222a49ea34857ff07f02f1e38b0 Author: christopherweems <github@christopherweems.com> Date: Sat Mar 19 12:53:31 2022 -0400 Fix typo in documentation for `MarkupVisitor` (#26) Co-authored-by: Christopher Weems <hello@christopherweems.com>
Includes the following changes: commit 7e704622ef98b3cc9233283b6298ed61806ddb43 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 5cc5656732244237066214bc976570f67cfe47b7 Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array.
Includes the following changes: commit 7e704622ef98b3cc9233283b6298ed61806ddb43 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (swiftlang#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 5cc5656732244237066214bc976570f67cfe47b7 Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (swiftlang#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array.
Includes the following changes: commit 7e704622ef98b3cc9233283b6298ed61806ddb43 Author: Ethan Kusters <ekusters@apple.com> Date: Sat May 21 14:02:22 2022 -0700 Correctly set `indexInParent` in `Markup.child(at:)` (#45) This fixes a recent regression where `Markup.child(at:)` began returning markup with incorrect metadata resulting in out-of-bounds errors. The `indexInParent` value of a child is unrelated to the parent's `indexInParent`. This was missed initially because tests were only checking for children of the first item where `indexInParent` would be 0. A new test has been added that asserts `Markup.child(at:)` returns correct values for children of nested items as well. commit 5cc5656732244237066214bc976570f67cfe47b7 Author: Ethan Kusters <ekusters@apple.com> Date: Fri May 20 18:53:24 2022 -0700 Improve performance of `Markup.child(at:)` method (#44) Improves the performance of `Markup.child(at:)` by refactoring to removing the need to iterate over all previous elements in the child array.
Summary
Requirements
Solution
DocC-Render will ship with two
index.html
files. One that includes templating syntax (template-index.html
) for the required base path replacement, and one that does not (index.html
).docc convert is updated to only include the base
index.html
file unless the new flag is passed. This will preserve existing behavior.When
docc convert --transform-for-static-hosting
is invoked with the new flag and base path replacement is required, the newtemplate-index.html
file will be used, the base path swapped, and it will be copied to all necessary locations.When
docc process-archive transform-for-static-hosting
is invoked and base path replacement is required, any existing DocC-Render template files will be deleted, and replaced with the one in the Toolchain.By default, docc will perform in-place transformation of the given documentation archive.
When
docc process-archive transform-for-static-hosting --output-path <path>
is invoked, the given DocCArchive will not be modified. The compatible version will be placed at the given output path.Dependencies
Static Template Support in Docc-Render
swiftlang/swift-docc-render#24
Testing
Testing will be from the command line. You will need to ensure
export DOCC_HTML_DIR="<path to DocC-Render dist>"
is using adist
folder from a version ofDocC-Render
that produces anindex-template.html
file.A suitable test DocC-Render Template is attached to the PR
Tests
docc convert
and check a archive is still produced correctlydocc convert --tranform-for-static-hosting
and check the correct folder structure is created and the folders contain the a validindex.html
docc convert --tranform-for-static-hosting --static-hosting-base-path <some value>
and check the correct folder structure is created and the folders contain the a validindex.html
which has been transformed with the base path.docc Process-Archive transform-for-static-hosting <path to archive>
against a clean.doccarchive
and test the output is the same as in test 2.docc Process-Archive transform-for-static-hosting <path to archive> --static-hosting-base-path <some value>
against a clean.doccarchive
and test the output is the same as in test 3.docc Process-Archive transform-for-static-hosting <path to archive> --outputPath <folder that not exist>
against a clean.doccarchive
and test new folder is created and the output is correct (data , images, all folders from HTML Template, documentation, tutorials)docc process-archive transform-for-static-hosting <path to archive> --outputPath <existing folder>
against a clean.doccarchive
test folder icontents have been replaced and the output is correct (data , images, all folders from HTML Template, documentation, tutorials) (repeat with an existing folder that contains hidden files and ensure the hidden files were not replaced)--static-hosting-base-path <some value>
parameter and check the index files have been appropriately amended.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/test
script and it succeededdist.zip