Merge pull request #550 from mzuehlke/doc-update

update plugin doc

Author: armanbilge

ci/src/main/scala/org/typelevel/sbt/TypelevelCiPlugin.scala

@@ -40,9 +40,9 @@ object TypelevelCiPlugin extends AutoPlugin {
     lazy val tlCiScalafixCheck =
       settingKey[Boolean]("Whether to do scalafix check in CI (default: false)")
     lazy val tlCiMimaBinaryIssueCheck =
-      settingKey[Boolean]("Whether to do MiMa binary issues check in CI (default: true)")
+      settingKey[Boolean]("Whether to do MiMa binary issues check in CI (default: false)")
     lazy val tlCiDocCheck =
-      settingKey[Boolean]("Whether to build API docs in CI (default: true)")
+      settingKey[Boolean]("Whether to build API docs in CI (default: false)")
 
     lazy val tlCiDependencyGraphJob =
       settingKey[Boolean]("Whether to add a job to submit dependencies to GH (default: true)")

docs/customization.md

@@ -11,42 +11,56 @@ Instead of using the super-plugins, for finer-grained control you can always add
 
 ### sbt-typelevel-kernel
 - `TypelevelKernelPlugin`
-- `tlIsScala3` (setting): true if `scalaVersion` is 3.x
-- `tlReplaceCommandAlias` (method): replace a `addCommandAlias` definition
-- `tlReleaseLocal` (command): alias for `+publishLocal`
+- `tlIsScala3` (setting): `true`, if `scalaVersion` is 3.x.
+- `tlSkipIrrelevantScalas` (setting): `true`, if should `skip` for `scalaVersion` not in `crossScalaVersions`.
+- `tlReplaceCommandAlias` (method): Replace a `addCommandAlias` definition.
+- `tlReleaseLocal` (command): Alias for `+publishLocal`.
 
 ### sbt-typelevel-versioning
-- `TypelevelVersioningPlugin`: Establishes a git-based, early semantic versioning scheme
-- `tlBaseVersion` (setting): the series your project is in. e.g., 0.2, 3.5
-- `tlUntaggedAreSnapshots` (setting): If true, an untagged commit is given a snapshot version, e.g. `0.4.1-17-00218f9-SNAPSHOT`. If false, it is given a release version, e.g. `0.4.1-17-00218f9`. (default: true)
+- `TypelevelVersioningPlugin`: Establishes a git-based, early semantic versioning scheme.
+- `tlBaseVersion` (setting): The series your project is in, e.g., 0.2, 3.5.
+- `tlUntaggedAreSnapshots` (setting): If true, an untagged commit is given a snapshot version, e.g. `0.4.1-17-00218f9-SNAPSHOT`. If false, it is given a release version, e.g. `0.4.1-17-00218f9` (default: true).
 
 ### sbt-typelevel-mima
 - `TypelevelMimaPlugin`: Determines previous MiMa artifacts via your `version` setting and git tags.
 - `tlVersionIntroduced` (setting): A map `scalaBinaryVersion -> version` e.g. `Map("2.13" -> "1.5.2", "3" -> "1.7.1")` used to indicate that a particular `crossScalaVersions` value was introduced in a given version (default: empty).
+- `tlMimaPreviousVersions` (setting): A set of previous versions to compare binary-compatibility against.
 
 ### sbt-typelevel-sonatype
 - `TypelevelSonatypePlugin`: Sets up publishing to Sonatype/Maven.
-- `tlRelease` (command): check binary-compatibility and `+publish` to Sonatype
-- `tlSonatypeUseLegacyHost` (setting): publish to `oss.sonatype.org` instead of `s01.oss.sonatype.org` (default: false)
+- `tlSonatypeUseLegacyHost` (setting): Publish to `oss.sonatype.org` instead of `s01.oss.sonatype.org` (default: false).
+- `tlRelease` (command): Check binary-compatibility and `+publish` to Sonatype.
+- `TypelevelUnidocPlugin`: Sets up publishing a Scaladoc-only artifact to Sonatype/Maven.
 
 ### sbt-typelevel-settings
 - `TypelevelSettingsPlugin`: Good and/or opinionated defaults for scalac settings etc., inspired by sbt-tpolecat.
 - `tlFatalWarnings` (setting): Convert compiler warnings into errors (default: false).
+- `tlJdkRelease` (setting): JVM target version for the compiled bytecode (default: Some(8)).
 
 ### sbt-typelevel-github
 - `TypelevelGitHubPlugin`: Populates boilerplate settings assuming you are using GitHub.
-- `TypelevelScalaJSGitHubPlugin`: Points your sourcemaps to GitHub permalinks. Only activated for Scala.js projects.
+- `tlGitHubRepo` (setting): The name of this repository on GitHub.
 - `tlGitHubDev(user, fullName)` (method): Helper to create a `Developer` entry from a GitHub username.
+- `TypelevelScalaJSGitHubPlugin`: Points your sourcemaps to GitHub permalinks. Only activated for Scala.js projects.
+- `TypelevelScalaNativeGitHubPlugin`: Points your sourcemaps to GitHub permalinks. Only activated for Scala Native projects.
 
 ### sbt-typelevel-ci
 - `TypelevelCiPlugin`: Sets up GitHub actions to run tests and check binary-compatibility in CI.
+- `tlCiHeaderCheck` (setting): Whether to do header check in CI (default: `false`).
+- `tlCiScalafmtCheck` (setting): Whether to do scalafmt check in CI (default: `false`).
+- `tlCiScalafixCheck` (setting): Whether to do scalafix check in CI (default: `false`).
+- `tlCiMimaBinaryIssueCheck` (setting): Whether to do MiMa binary issues check in CI (default: `false`).
+- `tlCiDocCheck` (setting): Whether to build API docs in CI (default: `false`).
+- `tlCiDependencyGraphJob` (setting): Whether to add a job to submit dependencies to GH (default: `true`)
+- `tlCiStewardValidateConfig` (setting): The location of the Scala Steward config to validate (default: `.scala-steward.conf`, if exists).
 - `tlCrossRootProject` (method): helper to create a `root` project that can aggregate both `Project`s and `CrossProject`s. Automatically creates separate jobs in the CI matrix for each platform (JVM, JS, etc.).
 
 ### sbt-typelevel-sonatype-ci-release
 - `TypelevelSonatypeCiReleasePlugin`: Sets up GitHub actions to publish to Sonatype in CI.
 - Requires the `SONATYPE_USERNAME` and `SONATYPE_PASSWORD` secrets
-- `tlCiReleaseTags` (setting): Controls whether or not v-prefixed tags should be released from CI (default true).
-- `tlCiReleaseBranches`: The branches in your repository to release from in CI on every push. Depending on your versioning scheme, they will be either snapshots or (hash) releases. Leave this empty if you only want CI releases for tags. (default: `[]`).
+- `tlCiReleaseTags` (setting): Controls whether or not v-prefixed tags should be released from CI (default `true`).
+- `tlCiReleaseBranches` (setting): The branches in your repository to release from in CI on every push. Depending on your versioning scheme, they will be either snapshots or (hash) releases. Leave this empty if you only want CI releases for tags. (default: `[]`).
+- `tlCiRelease` (command): Performs a `tlRelease` from the CI and reports to GH step summary.
 
 ### sbt-typelevel-ci-signing
 - `TypelevelCiSigningPlugin`: Sets up GitHub actions to sign your artifacts in CI.
@@ -56,15 +70,36 @@ Instead of using the super-plugins, for finer-grained control you can always add
 ### sbt-typelevel-ci-release
 - `TypelevelCiReleasePlugin`: The super-plugin that sets you up with versioning, mima, signing, and sonatype publishing, all in GitHub actions.
 
+### sbt-typelevel-scalafix
+- `TypelevelScalafixPlugin`
+- `tlTypelevelScalafixVersion` (setting): The version of typelevel-scalafix to add to the scalafix dependency classpath.
+
 ### sbt-typelevel
 - `TypelevelPlugin`: The super-super-plugin intended for bootstrapping the typical Typelevel project. Sets up CI release including snapshots, scalac settings, headers, and formatting.
 
 ### sbt-typelevel-site
--  `TypelevelSitePlugin`: Sets up an [mdoc](https://scalameta.org/mdoc/)/[Laika](https://typelevel.org/Laika/)-generated website, automatically published to GitHub pages in CI.
+- `TypelevelSitePlugin`: Sets up an [mdoc](https://scalameta.org/mdoc/)/[Laika](https://typelevel.org/Laika/)-generated website, automatically published to GitHub pages in CI.
+- `tlSiteHelium` (setting): The Helium theme configuration and extensions.
+- `tlSiteIsTypelevelProject` (setting): Indicates whether the generated site should be pre-populated with UI elements specific to Typelevel Organization or Affiliate projects (default: None).
+- `tlSiteApiUrl` (setting): URL to the API docs (default: `None`).
+- `tlSiteApiModule` (setting): The module that publishes API docs (default: `None`).
+- `tlSiteApiPackage` (setting): The top-level package for your API docs (e.g. org.typlevel.sbt).
+- `tlSiteKeepFiles` (setting): Whether to keep existing files when deploying site (default: `true`).
+- `tlSiteGenerate` (setting): A sequence of workflow steps which generates the site (default: `[Sbt(List("tlSite"))]`).
+- `tlSitePublish` (setting): A sequence of workflow steps which publishes the site (default: `peaceiris/actions-gh-pages`).
 - `tlSitePublishBranch` (setting): The branch to publish the site from on every push. Set this to `None` if you only want to update the site on tag releases. (default: `main`)
 - `tlSitePublishTags` (setting): Defines whether the site should be published on tag releases. Note on setting this to `true` requires the `tlSitePublishBranch` setting to be set to `None`. (default: `false`)
-- `tlSiteApiUrl` (setting): URL to the API docs. (default: `None`)
-- `tlSiteHeliumConfig` (setting): the Laika Helium config. (default: how the sbt-typelevel site looks)
+- `tlSite` (task): Generate the site (default: runs mdoc then laika).
+- `tlSitePreview` (task): Start a live-reload preview server (combines mdoc --watch with laikaPreview).
+
+### sbt-typelevel-mergify
+- `MergifyPlugin`: Sets up .mergify.yml file generation
+- `mergifyPrRules` (setting): The mergify pull request rules.
+- `mergifyStewardConfig` (setting): Config for the automerge rule for Scala Steward PRs, set to `None` to disable.
+- `mergifyRequiredJobs` (setting): Ids for jobs that must succeed for merging (default: `[build]`).
+- `mergifySuccessConditions` (setting): Success conditions for merging (default: auto-generated from `mergifyRequiredJobs` setting).
+- `mergifyGenerate` (task): Generates (and overwrites if extant) a .mergify.yml according to configuration.
+- `mergifyCheck` (task): Checks to see if the .mergify.yml files are equivalent to what would be generated and errors if otherwise.
 
 ## Dependency diagram
 

docs/site.md

@@ -1,13 +1,9 @@
 # sbt-typelevel-site
 
-<<<<<<< HEAD
 **sbt-typelevel-site** is an optional plugin for generating websites with [mdoc](https://scalameta.org/mdoc/)
-and [Laika](https://planet42.github.io/Laika/) and deploying to GitHub Pages from CI.
+and [Laika](https://typelevel.org/Laika/) and deploying to GitHub Pages from CI.
 You can add it to your build alongside either the  **sbt-typelevel** or **sbt-typelevel-ci-release** plugin
 or also use it stand-alone.
-=======
-**sbt-typelevel-site** is an optional plugin for generating websites with [mdoc](https://scalameta.org/mdoc/) and [Laika](https://typelevel.org/Laika/) and deploying to GitHub Pages from CI. You can add it to your build alongside either the  **sbt-typelevel** or **sbt-typelevel-ci-release** plugin or also use it stand-alone.
->>>>>>> series/0.4
 
 ## Quick start
 
@@ -29,12 +25,8 @@ lazy val docs = project.in(file("site")).enablePlugins(TypelevelSitePlugin)
 Place your `.md` files in the `docs/` directory of your project. To preview locally, run `docs/tlSitePreview`.
 This will start a preview server at http://localhost:4242.
 
-<<<<<<< HEAD
-The site is generated using [mdoc](https://scalameta.org/mdoc/) and [Laika](https://planet42.github.io/Laika/)
+The site is generated using [mdoc](https://scalameta.org/mdoc/) and [Laika](https://typelevel.org/Laika/)
 and published to the `gh-pages` branch on every push to the specified branch.
-=======
-The site is generated using [mdoc](https://scalameta.org/mdoc/) and [Laika](https://typelevel.org/Laika/) and published to the `gh-pages` branch on every push to the specified branch.
->>>>>>> series/0.4
 
 You will also need to configure your repository settings:
 
@@ -88,7 +80,7 @@ With the flag above (which defaults to `false`) these additional settings apply:
 ### Customization
 
 All customization options are based on Laika's configuration APIs for which we refer you to the comprehensive [Laika manual][Laika]
-and specifically the [`laikaTheme` setting](https://planet42.github.io/Laika/0.18/02-running-laika/01-sbt-plugin.html#laikatheme-setting).
+and specifically the [`laikaTheme` setting](https://typelevel.org/Laika/latest/02-running-laika/01-sbt-plugin.html#laikatheme-setting).
 
 @:callout(warning)
 For all code examples in the Laika manual you need to replace `Helium.defaults` with `tlSiteHelium.value`
@@ -122,13 +114,13 @@ Some of the customization options which are most likely of interest in the conte
 For a complete list of customization options please see the full [Laika] documentation.
 
 
-[Laika]: https://planet42.github.io/Laika/index.html
+[Laika]: https://typelevel.org/Laika/
 [http4s]: https://http4s.org/
-[Versioned Documentation]: https://planet42.github.io/Laika/0.18/03-preparing-content/01-directory-structure.html#versioned-documentation
-[Website Landing Page]: https://planet42.github.io/Laika/0.18/03-preparing-content/03-theme-settings.html#website-landing-page
-[Colors]: https://planet42.github.io/Laika/0.18/03-preparing-content/03-theme-settings.html#colors
-[Fonts]: https://planet42.github.io/Laika/0.18/03-preparing-content/03-theme-settings.html#fonts
-[laika-nav]: https://planet42.github.io/Laika/0.18/03-preparing-content/03-theme-settings.html#navigation-links-favicons
+[Versioned Documentation]: https://typelevel.org/Laika/latest/03-preparing-content/01-directory-structure.html#versioned-documentation
+[Website Landing Page]: https://typelevel.org/Laika/latest/03-preparing-content/03-theme-settings.html#website-landing-page
+[Colors]: https://typelevel.org/Laika/latest/03-preparing-content/03-theme-settings.html#colors
+[Fonts]: https://typelevel.org/Laika/latest/03-preparing-content/03-theme-settings.html#fonts
+[laika-nav]: https://typelevel.org/Laika/latest/03-preparing-content/03-theme-settings.html#navigation-links-favicons-footer
 
 
 ## FAQ
@@ -157,10 +149,3 @@ lazy val unidocs = project
     ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(core.jvm, heffalump)
   )
 ```
-<<<<<<< HEAD
-=======
-
-### How can I customize my website's appearance?
-
-We refer you to the comprehensive [Laika manual](https://typelevel.org/Laika/index.html) and specifically the [`laikaTheme` setting](https://typelevel.org/Laika/0.18/02-running-laika/01-sbt-plugin.html#laikatheme-setting).
->>>>>>> series/0.4

settings/src/main/scala/org/typelevel/sbt/TypelevelSettingsPlugin.scala

@@ -37,7 +37,7 @@ object TypelevelSettingsPlugin extends AutoPlugin {
       settingKey[Boolean]("Convert compiler warnings into errors (default: false)")
     lazy val tlJdkRelease =
       settingKey[Option[Int]](
-        "JVM target version for the compiled bytecode, None results in default scalac and javac behavior (no --release flag is specified). (default: None, supported values: 8, 9, 10, 11, 12, 13, 14, 15, 16, 17)")
+        "JVM target version for the compiled bytecode, None results in default scalac and javac behavior (no compiler flag is added) (default: Some(8))")
   }
 
   import autoImport._