[docs] Minimal docc setup and landing page #226
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ktoso
commented
Jul 26, 2022
| @@ -20,6 +20,9 @@ let package = Package( | |||
| products: [ | |||
| .library(name: "Logging", targets: ["Logging"]), | |||
| ], | |||
| dependencies: [ | |||
There was a problem hiding this comment.
To preview docs: swift package --disable-sandbox preview-documentation
yim-lee
reviewed
Jul 26, 2022
Sources/Logging/Logging.swift
Outdated
| @@ -103,7 +104,7 @@ extension Logger { | |||
|
|
|||
| /// Log a message passing the log level as a parameter. | |||
| /// | |||
| /// If the `logLevel` passed to this method is more severe than the `Logger`'s `logLevel`, it will be logged, | |||
| /// If the ``logLevel`` passed to this method is more severe than the `Logger`'s `logLevel`, it will be logged, | |||
There was a problem hiding this comment.
Suggested change
| /// If the ``logLevel`` passed to this method is more severe than the `Logger`'s `logLevel`, it will be logged, | |
| /// If the ``logLevel`` passed to this method is more severe than the `Logger`'s ``logLevel``, it will be logged, |
tomerd
reviewed
Jul 26, 2022
| @@ -0,0 +1,30 @@ | |||
| # ``Logging`` | |||
There was a problem hiding this comment.
how about we standardize on Sources/<Module>/Documentation.docc/index.md or Sources/<Module>/Docs.docc/index.md for the "landing page"
There was a problem hiding this comment.
I'll check if that works... docc has a lot of weird assumptions about "same name".
This is the style they advertise, and it's a bit confusing to be honest...
Filename of the md file can be different indeed though -- index.md could be good! 👍
There was a problem hiding this comment.
Ok yeap that works -- sounds good to me.
Co-authored-by: Yim Lee <[email protected]>
|
Need to swap the Package.swift style here |
|
Swapped the package style, merging |
renovate bot
referenced
this pull request
in cgrindel/rules_swift_package_manager
Mar 30, 2023
[](https://renovatebot.com) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [apple/swift-log](https://togithub.com/apple/swift-log) | minor | `from: "1.4.4"` -> `from: "1.5.2"` | --- ### Release Notes <details> <summary>apple/swift-log</summary> ### [`v1.5.2`](https://togithub.com/apple/swift-log/releases/tag/1.5.2) [Compare Source](https://togithub.com/apple/swift-log/compare/1.5.1...1.5.2) #### Primary change Address too aggressive warning logging on LogHandlers that do not support `MetadataProvider`. The warning would be emitted too frequently, resulting in flooding logs with warnings. Instead, the warning is now emitted once per log handler type. #### What's Changed - Avoid logging warnings when handler does not support metadataproviders by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/252](https://togithub.com/apple/swift-log/pull/252) - Handle providers properly in multiplex log handler by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/254](https://togithub.com/apple/swift-log/pull/254) - Add CI for Swift 5.8 and update nightly to Ubuntu 22.04 by [@​yim-lee](https://togithub.com/yim-lee) in [https://github.com/apple/swift-log/pull/255](https://togithub.com/apple/swift-log/pull/255) **Full Changelog**: apple/swift-log@1.5.1...1.5.2 ### [`v1.5.1`](https://togithub.com/apple/swift-log/releases/tag/1.5.1) [Compare Source](https://togithub.com/apple/swift-log/compare/1.5.0...1.5.1) #### Summary This patch release focuses on minor cleanups to ergonomics of setting metadata providers with the default stream log handlers, and fixes a bug in the default handler not printing the provided extra metadata by default (it does now). Thank you to [@​slashmo](https://togithub.com/slashmo) for quickly noticing and providing a patch for the latter! #### What's Changed - Allow passing explicit provider into the stream handlers by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/250](https://togithub.com/apple/swift-log/pull/250) - Emit correct metadata from StreamLogHandler by [@​slashmo](https://togithub.com/slashmo) in [https://github.com/apple/swift-log/pull/251](https://togithub.com/apple/swift-log/pull/251) **Full Changelog**: apple/swift-log@1.5.0...1.5.1 ### [`v1.5.0`](https://togithub.com/apple/swift-log/releases/tag/1.5.0) [Compare Source](https://togithub.com/apple/swift-log/compare/1.4.4...1.5.0) ### Changes #### Swift version support This release drops support for Swift 5.0. Swift 5.1+ remain supported for the time being. #### Logger.MetadataProvider This release introduces metadata providers! They are an additional way to add metadata to your log statements automatically whenever a log statement is about to be made. This works extremely well with systems like distributed tracing, that may pick up trace identifiers and other information from the task-local context from where the log statement is being made. The feature came with a [swift evolution style proposal](https://togithub.com/apple/swift-log/blob/main/proposals/0001-metadata-providers.md) introduction to the "why?" and "how?" of this feature you may find interesting. Metadata providers are used like this: ```swift import Logging enum Namespace { @​TaskLocal static var simpleTraceID: String? } let simpleTraceIDMetadataProvider = Logger.MetadataProvider { guard let traceID = Namespace.simpleTraceID else { return [:] } return ["simple-trace-id": .string(traceID)] } LoggingSystem.bootstrap({ label, metadataProvider in myCoolLogHandler(label: label, metadataProvider: metadataProvider) }, metadataProvider: simpleTraceIDMetadataProvider) ``` which in turn makes every `Logger` on this `LoggingSystem` add this contextual metadata to log statements automatically: ```swift let log = Logger(label: "hello") Namespace.$simpleTraceID.withValue("1234-5678") { test() } func test() { log.info("test log statement") } // [info] [simple-trace-id: 1234-5678] test log statement ``` ##### Adoption in `LogHandler`s In order to support this new feature in your log handlers, please make it accept a `MetadataProvider?` at creation, and store it as: ```swift struct MyHandler: LogHandler { // ... public var metadataProvider: Logger.MetadataProvider? // ... } ``` #### What's Changed ##### Highlight - Metadata Providers (e.g. for Distributed Tracing) in LogHandlers by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/238](https://togithub.com/apple/swift-log/pull/238) ##### Other changes - \[docs] Minimal docc setup and landing page by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/226](https://togithub.com/apple/swift-log/pull/226) - \=docc Make docs use symbol references by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/230](https://togithub.com/apple/swift-log/pull/230) - \=docc Move to multiple Package.swift files by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/231](https://togithub.com/apple/swift-log/pull/231) - Undo 5.7 package files, not needed yet by [@​ktoso](https://togithub.com/ktoso) in [https://github.com/apple/swift-log/pull/232](https://togithub.com/apple/swift-log/pull/232) - Update README: Add missing Source param by [@​Rusik](https://togithub.com/Rusik) in [https://github.com/apple/swift-log/pull/233](https://togithub.com/apple/swift-log/pull/233) - Fix build for wasm by [@​ahti](https://togithub.com/ahti) in [https://github.com/apple/swift-log/pull/236](https://togithub.com/apple/swift-log/pull/236) - Add .spi.yml for Swift Package Index DocC support by [@​yim-lee](https://togithub.com/yim-lee) in [https://github.com/apple/swift-log/pull/240](https://togithub.com/apple/swift-log/pull/240) - Fixes link to Supabase repository in README.md by [@​timobollwerk](https://togithub.com/timobollwerk) in [https://github.com/apple/swift-log/pull/245](https://togithub.com/apple/swift-log/pull/245) #### New Contributors - [@​Rusik](https://togithub.com/Rusik) made their first contribution in [https://github.com/apple/swift-log/pull/233](https://togithub.com/apple/swift-log/pull/233) - [@​ahti](https://togithub.com/ahti) made their first contribution in [https://github.com/apple/swift-log/pull/236](https://togithub.com/apple/swift-log/pull/236) - [@​timobollwerk](https://togithub.com/timobollwerk) made their first contribution in [https://github.com/apple/swift-log/pull/245](https://togithub.com/apple/swift-log/pull/245) **Full Changelog**: apple/swift-log@1.4.4...1.5.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/cgrindel/swift_bazel). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNS4yMi4xIiwidXBkYXRlZEluVmVyIjoiMzUuMjIuMSJ9--> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
](https://renovatebot.com){kind=link}
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Minimal setup for docc documentation.
Honestly I'm very tempted to rip out most of the
README.mdand put it into docc, any voices against doing that?README could still contain the list of implementations, as that's perhaps easier to just look up in the README while browsing github, but all the other information in README should be moved over to the docc docs -- sounds good?