Add DocC implementation of current docs #59
Conversation
This also bumps the minimum tools version to 5.5
| @@ -0,0 +1,55 @@ | |||
| # Common Mistakes | |||
|
|
|||
| An overview of common mistakes made while dealing with **Time** or its concepts in general. | |||
There was a problem hiding this comment.
Everywhere in the new markdown, I formatted the package's name to be bold, rather than monospaced to make it stand out more. That's just a personal style of mine, so please let me know if you have a different preference for referencing modules or libraries
These docs are 98% verbatim from their source. I made links to Foundation docs where missing, as well as used DocC symbol linking to provide a richer experience.
The only formatting changes I made were to fit within DocC structure, and where it made absolute sense to break up paragraphs.
|
Here's some screenshots!
|
|
My intention was to just seed the current documentation as DocC for now, leaving the content basically as-is with some early richer linking, and then maybe in a later PR actually editing/re-writing the documentation itself to be more of a first-class citizen as DocC. I'm not sure how you want to handle the docs at DocC links (obviously) break when trying to view the markdown in GitHub, so it's a bit substandard to not have a webhosted version of the docs, so I had figured you wanted to keep it as-is until hosting the DocC output |
| // swift-tools-version:5.5 | ||
| // The swift-tools-version declares the minimum version of Swift required to build this package. | ||
|
|
||
| import PackageDescription | ||
|
|
||
| let package = Package( | ||
| name: "Time", | ||
| products: [ | ||
| .library(name: "Time", targets: ["Time"]) | ||
| ], | ||
| dependencies: [ | ||
|
|
||
| ], | ||
| targets: [ | ||
| .target(name: "Time", dependencies: []), | ||
|
|
||
| .testTarget(name: "TimeTests", dependencies: ["Time"]), | ||
| ] | ||
| ) |
There was a problem hiding this comment.
Is this Package.swift necessary if the primary one is set to request Swift 5.5?
There was a problem hiding this comment.
Pre 5.5, the compiler emits a warning of unused/unrecognized files and suggests explicitly excluding the DocC file.
To be honest, I’m not 100% sure if that warming is emitted when downstream users are building the library as a dependency, but it definitely emits a warning when building the project itself
There was a problem hiding this comment.
I just tested this by depending on a special branch that doesn't do this conditional package manifest stuff and I can conform that the compiler warning does get emitted when the library is built by a downstream user.
found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
/Users/.../Library/Developer/Xcode/DerivedData/test-crmhlaksfvpqexbqodizljvczqrs/SourcePackages/checkouts/time/Sources/Time/Documentation.docc
There was a problem hiding this comment.
Also, if your Package.swift doesn't somewhere explicitly say 5.5 is a supported build flavor, the DocC output is not generated
There was a problem hiding this comment.
Oh, shoot. I'm seeing my mistake - I didn't properly switch the minimum version in question... I'll fix it!
| @@ -0,0 +1,55 @@ | |||
| # Common Mistakes | |||
|
|
|||
| An overview of common mistakes made while dealing with **Time** or its concepts in general. | |||
|
|
||
| For example, if `today` is `February 29th, 2020`, then: | ||
| - `answer1` will produce `April 1st, 2020` (29 Feb + 1 day = 1 Mar; 1 Mar + 1 month = 1 Apr) | ||
| - `answer2` will product `March 30th, 2020` (29 Feb + 1 month = 29 Mar; 29 Mar + 1 day = 30 Mar) |
There was a problem hiding this comment.
Typo (originally mine, I think): product → produce
Motivation
DocC is a fantastic tool that was announced at WWDC 2021, and full support was released with Swift 5.5
Supporting documentation within DocC gives additional capabilities to developers who work with Time to have better symbol linking and usage guides available while offline, and generated to render within Xcode itself.
Changes Made
Documentation/folder almost verbatimResults
DocC support!