From ce873ff9f74d78b4eab975e78e65b06c0d580fbd Mon Sep 17 00:00:00 2001 From: Arman Bilge Date: Wed, 6 Apr 2022 05:30:46 +0000 Subject: [PATCH] WIP migrate site to Laika --- CONTRIBUTING.md | 8 +- README.md | 38 +-- build.sbt | 18 +- docs/{src/main/mdoc => }/algebra.md | 6 +- docs/{src/main/mdoc => }/colophon.md | 10 +- docs/contributing.md | 1 + docs/datatypes.md | 5 + docs/{src/main/mdoc => }/datatypes/chain.md | 8 - docs/{src/main/mdoc => }/datatypes/const.md | 7 - docs/{src/main/mdoc => }/datatypes/contt.md | 7 - docs/datatypes/directory.conf | 1 + docs/{src/main/mdoc => }/datatypes/either.md | 7 - docs/{src/main/mdoc => }/datatypes/eithert.md | 7 - docs/{src/main/mdoc => }/datatypes/eval.md | 7 - .../mdoc => }/datatypes/freeapplicative.md | 7 - .../main/mdoc => }/datatypes/freemonad.md | 8 - .../main/mdoc => }/datatypes/functionk.md | 7 - docs/{src/main/mdoc => }/datatypes/id.md | 7 - docs/{src/main/mdoc => }/datatypes/ior.md | 7 - docs/{src/main/mdoc => }/datatypes/iort.md | 7 - docs/{src/main/mdoc => }/datatypes/kleisli.md | 7 - docs/{src/main/mdoc => }/datatypes/nel.md | 7 - docs/{src/main/mdoc => }/datatypes/nested.md | 8 +- docs/{src/main/mdoc => }/datatypes/oneand.md | 7 - docs/{src/main/mdoc => }/datatypes/optiont.md | 7 - docs/{src/main/mdoc => }/datatypes/state.md | 7 - .../main/mdoc => }/datatypes/validated.md | 7 - docs/{src/main/mdoc => }/datatypes/writer.md | 29 +-- docs/{src/main/mdoc => }/datatypes/writert.md | 45 ++-- docs/directory.conf | 17 ++ docs/{src/main/mdoc => }/faq.md | 100 ++++---- docs/{src/main/mdoc => }/guidelines.md | 0 .../microsite => }/img/cats-badge-big.png | Bin .../microsite => }/img/cats-badge-normal.png | Bin .../microsite => }/img/cats-badge-tiny.png | Bin .../microsite => }/img/cats-badge.svg | 0 .../microsite => }/img/cats-logo.png | Bin .../microsite => }/img/cats-logo.svg | 0 .../resources/microsite => }/img/cats2.png | Bin .../microsite => }/img/donate-button.png | Bin .../resources/microsite => }/img/favicon.png | Bin .../microsite => }/img/jumbotron_pattern.png | Bin .../img/jumbotron_pattern2x.png | Bin .../microsite => }/img/missing-avatar.svg | 0 .../microsite => }/img/navbar_brand.png | Bin .../microsite => }/img/navbar_brand2x.png | Bin .../resources/microsite => }/img/parallel.png | Bin .../resources/microsite => }/img/poster.png | Bin .../microsite => }/img/sidebar_brand.png | Bin .../microsite => }/img/sidebar_brand2x.png | Bin .../microsite => }/img/sponsors/47_degree.png | Bin .../img/sponsors/commercetools.png | Bin .../microsite => }/img/sponsors/ebiznext.png | Bin .../sponsors/evolution_gaming_engineering.png | Bin .../img/sponsors/inner-product.png | Bin .../microsite => }/img/sponsors/iterators.png | Bin .../img/sponsors/triplequote.png | Bin .../img/sponsors/underscore.png | Bin docs/index.md | 1 + .../resources/microsite => }/js/sponsors.js | 14 +- docs/{src/main/mdoc => }/jump_start_guide.md | 14 +- docs/{src/main/mdoc => }/motivations.md | 14 +- docs/{src/main/mdoc => }/nomenclature.md | 9 +- .../main/mdoc => }/resources_for_learners.md | 8 +- docs/src/main/mdoc/datatypes.md | 13 -- docs/src/main/mdoc/typeclasses.md | 7 - .../main/resources/microsite/css/override.css | 3 - .../main/resources/microsite/data/menu.yml | 220 ------------------ .../main/mdoc/typeclasses => }/typeclasses.md | 28 +-- .../main/mdoc => }/typeclasses/alternative.md | 9 +- .../main/mdoc => }/typeclasses/applicative.md | 11 +- .../typeclasses/applicativemonaderror.md | 7 - .../typeclasses/applicativetraverse.md | 7 - docs/{src/main/mdoc => }/typeclasses/arrow.md | 7 - .../main/mdoc => }/typeclasses/arrowchoice.md | 15 +- .../main/mdoc => }/typeclasses/bifunctor.md | 7 - .../main/mdoc => }/typeclasses/bimonad.md | 7 - .../main/mdoc => }/typeclasses/comonad.md | 7 - .../mdoc => }/typeclasses/contravariant.md | 7 - .../typeclasses/contravariantmonoidal.md | 7 - docs/typeclasses/directory.conf | 1 + docs/{src/main/mdoc => }/typeclasses/eq.md | 8 - .../main/mdoc => }/typeclasses/foldable.md | 7 - .../main/mdoc => }/typeclasses/functor.md | 7 - .../main/mdoc => }/typeclasses/imports.md | 9 +- .../main/mdoc => }/typeclasses/invariant.md | 7 - .../typeclasses/invariantmonoidal.md | 7 - .../main/mdoc => }/typeclasses/lawtesting.md | 8 +- docs/{src/main/mdoc => }/typeclasses/monad.md | 7 - .../{src/main/mdoc => }/typeclasses/monoid.md | 7 - .../main/mdoc => }/typeclasses/monoidk.md | 7 - .../mdoc => }/typeclasses/nonemptytraverse.md | 8 - .../main/mdoc => }/typeclasses/parallel.dot | 0 .../main/mdoc => }/typeclasses/parallel.md | 7 - .../main/mdoc => }/typeclasses/reducible.md | 8 - .../main/mdoc => }/typeclasses/semigroup.md | 7 - .../main/mdoc => }/typeclasses/semigroupk.md | 7 - docs/{src/main/mdoc => }/typeclasses/show.md | 7 - .../main/mdoc => }/typeclasses/traverse.md | 8 - .../{src/main/mdoc => }/typelevelEcosystem.md | 41 ++-- 100 files changed, 201 insertions(+), 803 deletions(-) rename docs/{src/main/mdoc => }/algebra.md (99%) rename docs/{src/main/mdoc => }/colophon.md (89%) create mode 120000 docs/contributing.md create mode 100644 docs/datatypes.md rename docs/{src/main/mdoc => }/datatypes/chain.md (98%) rename docs/{src/main/mdoc => }/datatypes/const.md (98%) rename docs/{src/main/mdoc => }/datatypes/contt.md (97%) create mode 100644 docs/datatypes/directory.conf rename docs/{src/main/mdoc => }/datatypes/either.md (98%) rename docs/{src/main/mdoc => }/datatypes/eithert.md (97%) rename docs/{src/main/mdoc => }/datatypes/eval.md (96%) rename docs/{src/main/mdoc => }/datatypes/freeapplicative.md (98%) rename docs/{src/main/mdoc => }/datatypes/freemonad.md (99%) rename docs/{src/main/mdoc => }/datatypes/functionk.md (97%) rename docs/{src/main/mdoc => }/datatypes/id.md (93%) rename docs/{src/main/mdoc => }/datatypes/ior.md (96%) rename docs/{src/main/mdoc => }/datatypes/iort.md (98%) rename docs/{src/main/mdoc => }/datatypes/kleisli.md (98%) rename docs/{src/main/mdoc => }/datatypes/nel.md (97%) rename docs/{src/main/mdoc => }/datatypes/nested.md (95%) rename docs/{src/main/mdoc => }/datatypes/oneand.md (84%) rename docs/{src/main/mdoc => }/datatypes/optiont.md (96%) rename docs/{src/main/mdoc => }/datatypes/state.md (98%) rename docs/{src/main/mdoc => }/datatypes/validated.md (99%) rename docs/{src/main/mdoc => }/datatypes/writer.md (81%) rename docs/{src/main/mdoc => }/datatypes/writert.md (79%) create mode 100644 docs/directory.conf rename docs/{src/main/mdoc => }/faq.md (77%) rename docs/{src/main/mdoc => }/guidelines.md (100%) rename docs/{src/main/resources/microsite => }/img/cats-badge-big.png (100%) rename docs/{src/main/resources/microsite => }/img/cats-badge-normal.png (100%) rename docs/{src/main/resources/microsite => }/img/cats-badge-tiny.png (100%) rename docs/{src/main/resources/microsite => }/img/cats-badge.svg (100%) rename docs/{src/main/resources/microsite => }/img/cats-logo.png (100%) rename docs/{src/main/resources/microsite => }/img/cats-logo.svg (100%) rename docs/{src/main/resources/microsite => }/img/cats2.png (100%) rename docs/{src/main/resources/microsite => }/img/donate-button.png (100%) rename docs/{src/main/resources/microsite => }/img/favicon.png (100%) rename docs/{src/main/resources/microsite => }/img/jumbotron_pattern.png (100%) rename docs/{src/main/resources/microsite => }/img/jumbotron_pattern2x.png (100%) rename docs/{src/main/resources/microsite => }/img/missing-avatar.svg (100%) rename docs/{src/main/resources/microsite => }/img/navbar_brand.png (100%) rename docs/{src/main/resources/microsite => }/img/navbar_brand2x.png (100%) rename docs/{src/main/resources/microsite => }/img/parallel.png (100%) rename docs/{src/main/resources/microsite => }/img/poster.png (100%) rename docs/{src/main/resources/microsite => }/img/sidebar_brand.png (100%) rename docs/{src/main/resources/microsite => }/img/sidebar_brand2x.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/47_degree.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/commercetools.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/ebiznext.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/evolution_gaming_engineering.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/inner-product.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/iterators.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/triplequote.png (100%) rename docs/{src/main/resources/microsite => }/img/sponsors/underscore.png (100%) create mode 120000 docs/index.md rename docs/{src/main/resources/microsite => }/js/sponsors.js (85%) rename docs/{src/main/mdoc => }/jump_start_guide.md (96%) rename docs/{src/main/mdoc => }/motivations.md (86%) rename docs/{src/main/mdoc => }/nomenclature.md (98%) rename docs/{src/main/mdoc => }/resources_for_learners.md (96%) delete mode 100644 docs/src/main/mdoc/datatypes.md delete mode 100644 docs/src/main/mdoc/typeclasses.md delete mode 100644 docs/src/main/resources/microsite/css/override.css delete mode 100644 docs/src/main/resources/microsite/data/menu.yml rename docs/{src/main/mdoc/typeclasses => }/typeclasses.md (82%) rename docs/{src/main/mdoc => }/typeclasses/alternative.md (96%) rename docs/{src/main/mdoc => }/typeclasses/applicative.md (96%) rename docs/{src/main/mdoc => }/typeclasses/applicativemonaderror.md (98%) rename docs/{src/main/mdoc => }/typeclasses/applicativetraverse.md (94%) rename docs/{src/main/mdoc => }/typeclasses/arrow.md (98%) rename docs/{src/main/mdoc => }/typeclasses/arrowchoice.md (90%) rename docs/{src/main/mdoc => }/typeclasses/bifunctor.md (95%) rename docs/{src/main/mdoc => }/typeclasses/bimonad.md (95%) rename docs/{src/main/mdoc => }/typeclasses/comonad.md (95%) rename docs/{src/main/mdoc => }/typeclasses/contravariant.md (94%) rename docs/{src/main/mdoc => }/typeclasses/contravariantmonoidal.md (94%) create mode 100644 docs/typeclasses/directory.conf rename docs/{src/main/mdoc => }/typeclasses/eq.md (93%) rename docs/{src/main/mdoc => }/typeclasses/foldable.md (97%) rename docs/{src/main/mdoc => }/typeclasses/functor.md (96%) rename docs/{src/main/mdoc => }/typeclasses/imports.md (72%) rename docs/{src/main/mdoc => }/typeclasses/invariant.md (95%) rename docs/{src/main/mdoc => }/typeclasses/invariantmonoidal.md (97%) rename docs/{src/main/mdoc => }/typeclasses/lawtesting.md (97%) rename docs/{src/main/mdoc => }/typeclasses/monad.md (97%) rename docs/{src/main/mdoc => }/typeclasses/monoid.md (95%) rename docs/{src/main/mdoc => }/typeclasses/monoidk.md (93%) rename docs/{src/main/mdoc => }/typeclasses/nonemptytraverse.md (92%) rename docs/{src/main/mdoc => }/typeclasses/parallel.dot (100%) rename docs/{src/main/mdoc => }/typeclasses/parallel.md (96%) rename docs/{src/main/mdoc => }/typeclasses/reducible.md (95%) rename docs/{src/main/mdoc => }/typeclasses/semigroup.md (96%) rename docs/{src/main/mdoc => }/typeclasses/semigroupk.md (95%) rename docs/{src/main/mdoc => }/typeclasses/show.md (94%) rename docs/{src/main/mdoc => }/typeclasses/traverse.md (97%) rename docs/{src/main/mdoc => }/typelevelEcosystem.md (98%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e91f63914..c1277b4d52 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ skip these steps and jump straight to submitting a pull request. 1. [Find something that belongs in cats](#find-something-that-belongs-in-cats) 2. [Let us know you are working on it](#let-us-know-you-are-working-on-it) - 3. [Build the project](#build-project) + 3. [Build the project](#build-the-project) 4. [Implement your contribution](#write-code) 5. [Write tests](#write-tests) 6. [Write documentation](#contributing-documentation) @@ -50,7 +50,7 @@ pull request. The preferred ways to do that are to either: Things that belong in Cats generally have the following characteristics: - * Their behavior is governed by well-defined [laws](https://typelevel.org/cats/typeclasses.html#laws). + * Their behavior is governed by well-defined [laws](typeclasses.html#laws). * They provide general abstractions. Laws help keep types consistent, and remove ambiguity or sensitivity @@ -133,7 +133,7 @@ builds: ### Write code -[See guidelines](https://typelevel.org/cats/guidelines.html). +[See guidelines](guidelines.html). ### Attributions @@ -164,7 +164,7 @@ for law checking, and imports all syntax and standard instances for convenience. rely heavily on serialization, such as `Spark`, will have strong compatibility with `Cats`. - Note that custom serialization tests are not required for instances of type classes which come from `algebra`, such as `Monoid`, because the `algebra` laws include a test for serialization. -- For testing your laws, it is advised to check [this guide](https://typelevel.org/cats/typeclasses/lawtesting.html). +- For testing your laws, it is advised to check [this guide](typeclasses/lawtesting.html). ### Binary compatibility diff --git a/README.md b/README.md index 96b09b6170..22cafeb83d 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ Cats is a library which provides abstractions for functional programming in the [Scala programming language](https://scala-lang.org). Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the -standard library. Cats strives to provide functional programming abstractions that are core, [binary compatible](http://typelevel.org/cats/#binary-compatibility-and-versioning), [modular](http://typelevel.org/cats/motivations#modularity), [approachable](http://typelevel.org/cats/motivations#approachability) and [efficient](http://typelevel.org//cats/motivations#efficiency). A broader goal of Cats is to provide a foundation for an [ecosystem of pure, typeful libraries](https://typelevel.org/cats/#ecosystem) to support functional programming in Scala applications. +standard library. Cats strives to provide functional programming abstractions that are core, [binary compatible](#binary-compatibility-and-versioning), [modular](motivations#modularity), [approachable](motivations#approachability) and [efficient](http://typelevel.org//cats/motivations#efficiency). A broader goal of Cats is to provide a foundation for an [ecosystem of pure, typeful libraries](#ecosystem) to support functional programming in Scala applications. -For more detail about Cats' motivations, go [here](http://typelevel.org/cats/motivations). +For more detail about Cats' motivations, go [here](motivations). ### Why "cats"? @@ -26,7 +26,7 @@ Regardless, you do not need to know anything about category theory to use Cats. ### Code Contributors This project exists thanks to [all the people who contribute](https://github.com/typelevel/cats/graphs/contributors). We welcome contributions to Cats and would love for you to help build -Cats. See our [contributor guide](https://typelevel.org/cats/contributing.html) for more +Cats. See our [contributor guide](contributing.html) for more information about how you can get involved as a developer. If you are looking for something to start with, [here is a beginner friendly list](https://github.com/typelevel/cats/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). ### Financial Contributors @@ -36,31 +36,31 @@ information about how you can get involved as a developer. If you are looking fo

Platinum Sponsors

Platinum sponsorship starts at $950 USD/month.
- +

Gold Sponsors

Gold Sponsorship starts at $420 USD/month.
- +

Silver Sponsors

Silver Sponsorship starts at $180 USD/month.
- +

Backers

Become a Backer with a recurring donation of just $5 USD/month.
- +

Other contributors

We thankfully accept one-time and recurring contributions as well.
- +
@@ -118,15 +118,15 @@ Past release notes for Cats are available in [CHANGES.md](https://github.com/typ Links: -1. Website: [typelevel.org/cats/](https://typelevel.org/cats/) -2. ScalaDoc: [typelevel.org/cats/api/](https://typelevel.org/cats/api/) -3. Type classes: [typelevel.org/cats/typeclasses](https://typelevel.org/cats/typeclasses.html) -4. Data types: [typelevel.org/cats/datatypes.html](https://typelevel.org/cats/datatypes.html) -5. Algebra overview: [typelevel.org/cats/algebra.html](https://typelevel.org/cats/algebra.html) -6. Glossary: [typelevel.org/cats/nomenclature.html](https://typelevel.org/cats/nomenclature.html) -7. Resources for Learners: [typelevel.org/cats/resources_for_learners.html](https://typelevel.org/cats/resources_for_learners.html) -8. FAQ: [typelevel.org/cats/faq.html](https://typelevel.org/cats/faq.html) -9. The Typelevel Ecosystem: [typelevel.org/cats/typelevelEcosystem.html](https://typelevel.org/cats/typelevelEcosystem.html) +1. Website: [typelevel.org/cats/]() +2. ScalaDoc: [typelevel.org/cats/api/](api/) +3. Type classes: [typelevel.org/cats/typeclasses](typeclasses.html) +4. Data types: [typelevel.org/cats/datatypes.html](datatypes.html) +5. Algebra overview: [typelevel.org/cats/algebra.html](algebra.html) +6. Glossary: [typelevel.org/cats/nomenclature.html](nomenclature.html) +7. Resources for Learners: [typelevel.org/cats/resources_for_learners.html](resources_for_learners.html) +8. FAQ: [typelevel.org/cats/faq.html](faq.html) +9. The Typelevel Ecosystem: [typelevel.org/cats/typelevelEcosystem.html](typelevelEcosystem.html) ### Community @@ -202,7 +202,7 @@ Here's a (non-exhaustive) list of companies that use Cats in production. Don't s - [Code Dx](https://codedx.com/) - [Codecentric](https://codecentric.de) - [Colisweb](https://www.colisweb.com/) -- [CompStak](compstak.com) +- [CompStak](https://compstak.com) - [Coya](https://coya.com/) - [Datum Brain](https://datumbrain.com/) - [Disney](https://disney.com/) @@ -335,7 +335,7 @@ relax this to a single sign-off. More detail in the [process document](https://g All code is available to you under the MIT license, available at http://opensource.org/licenses/mit-license.php and also in the -[COPYING](COPYING) file. The design is informed by many other +[COPYING](https://github.com/typelevel/cats/blob/main/COPYING) file. The design is informed by many other projects, in particular [Scalaz](https://github.com/scalaz/scalaz). Copyright the maintainers, 2015-2022. diff --git a/build.sbt b/build.sbt index 8455dff7e8..8f3b59bba9 100644 --- a/build.sbt +++ b/build.sbt @@ -23,7 +23,7 @@ val Scala213 = "2.13.8" val Scala3 = "3.0.2" ThisBuild / crossScalaVersions := Seq(Scala212, Scala213, Scala3) -ThisBuild / scalaVersion := Scala213 +ThisBuild / scalaVersion := Scala212 ThisBuild / tlFatalWarnings := { githubIsWorkflowBuild.value && !tlIsScala3.value @@ -361,6 +361,22 @@ lazy val binCompatTest = project .settings(testingDependencies) .dependsOn(core.jvm % Test) +lazy val docs = project + .in(file("site")) + .enablePlugins(TypelevelSitePlugin) + .settings( + laikaConfig ~= { _.withRawContent }, + tlSiteRelatedProjects := Seq( + "Cats Effect" -> url("https://typelevel.org/cats-effect"), + "mouse" -> url("https://typelevel.org/mouse"), + "Discipline" -> url("https://github.com/typelevel/discipline") + ), + libraryDependencies ++= Seq( + "org.typelevel" %%% "discipline-munit" % disciplineMunitVersion + ) + ) + .dependsOn(core.jvm, free.jvm, laws.jvm) + ThisBuild / organization := "org.typelevel" ThisBuild / organizationName := "Typelevel" ThisBuild / organizationHomepage := Some(url("https://typelevel.org")) diff --git a/docs/src/main/mdoc/algebra.md b/docs/algebra.md similarity index 99% rename from docs/src/main/mdoc/algebra.md rename to docs/algebra.md index 9607cc7685..7b4a99bbc6 100644 --- a/docs/src/main/mdoc/algebra.md +++ b/docs/algebra.md @@ -1,8 +1,4 @@ ---- -layout: docs -title: "Algebra Overview" -section: "algebra" ---- +{% laika.title = Algebra %} # Algebra Overview diff --git a/docs/src/main/mdoc/colophon.md b/docs/colophon.md similarity index 89% rename from docs/src/main/mdoc/colophon.md rename to docs/colophon.md index 851cd38c72..b21a8dcacc 100644 --- a/docs/src/main/mdoc/colophon.md +++ b/docs/colophon.md @@ -1,9 +1,5 @@ ---- -layout: page -title: "Colophon" -section: "colophon" -position: 60 ---- +# Colophon + Cats has been made a much better project, and is a much more enjoyable project to work on because of many of the other projects on which Cats is built. Many of these projects have had enhancements made in order @@ -26,4 +22,4 @@ There are other libraries that aim to foster Functional Programming in the Scala nature to Cats, also derived from scalaz. The Structures and Cats projects have had a healthy relationship of sharing both ideas and code. -For a full list of Cats and Typelevel related projects and libraries, take a look at [The Typelevel Ecosystem](https://typelevel.org/cats/typelevelEcosystem.html) +For a full list of Cats and Typelevel related projects and libraries, take a look at [The Typelevel Ecosystem](typelevelEcosystem.html) diff --git a/docs/contributing.md b/docs/contributing.md new file mode 120000 index 0000000000..44fcc63439 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/datatypes.md b/docs/datatypes.md new file mode 100644 index 0000000000..b151b8ebe5 --- /dev/null +++ b/docs/datatypes.md @@ -0,0 +1,5 @@ +{% laika.title = "Data Types" %} + +@:navigationTree { + entries = [ { target = "datatypes", depth = 2 } ] +} diff --git a/docs/src/main/mdoc/datatypes/chain.md b/docs/datatypes/chain.md similarity index 98% rename from docs/src/main/mdoc/datatypes/chain.md rename to docs/datatypes/chain.md index d7a5e98f73..97f046fba9 100644 --- a/docs/src/main/mdoc/datatypes/chain.md +++ b/docs/datatypes/chain.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "Chain" -section: "data" -source: "core/src/main/scala/cats/data/Chain.scala" -scaladoc: "#cats.data.Chain" ---- - # Chain `Chain` is a data structure that allows constant time prepending and appending. diff --git a/docs/src/main/mdoc/datatypes/const.md b/docs/datatypes/const.md similarity index 98% rename from docs/src/main/mdoc/datatypes/const.md rename to docs/datatypes/const.md index 181edd9d11..3f35826543 100644 --- a/docs/src/main/mdoc/datatypes/const.md +++ b/docs/datatypes/const.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Const" -section: "data" -source: "core/src/main/scala/cats/data/Const.scala" -scaladoc: "#cats.data.Const" ---- # Const At first glance `Const` seems like a strange data type - it has two type parameters, yet only stores a value of the first type. What possible use is it? As it turns out, it does diff --git a/docs/src/main/mdoc/datatypes/contt.md b/docs/datatypes/contt.md similarity index 97% rename from docs/src/main/mdoc/datatypes/contt.md rename to docs/datatypes/contt.md index 3253e8972b..6f6fb008ee 100644 --- a/docs/src/main/mdoc/datatypes/contt.md +++ b/docs/datatypes/contt.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "ContT" -section: "data" -source: "core/src/main/scala/cats/data/ContT.scala" -scaladoc: "#cats.data.ContT" ---- # ContT A pattern that appears sometimes in functional programming is that of a function diff --git a/docs/datatypes/directory.conf b/docs/datatypes/directory.conf new file mode 100644 index 0000000000..5a36448a4e --- /dev/null +++ b/docs/datatypes/directory.conf @@ -0,0 +1 @@ +laika.title = Data Types diff --git a/docs/src/main/mdoc/datatypes/either.md b/docs/datatypes/either.md similarity index 98% rename from docs/src/main/mdoc/datatypes/either.md rename to docs/datatypes/either.md index efafca0cce..f6d0577353 100644 --- a/docs/src/main/mdoc/datatypes/either.md +++ b/docs/datatypes/either.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Either" -section: "data" -source: "core/src/main/scala/cats/syntax/either.scala" -scaladoc: "#cats.syntax.EitherOps" ---- # Either In day-to-day programming, it is fairly common to find ourselves writing functions that diff --git a/docs/src/main/mdoc/datatypes/eithert.md b/docs/datatypes/eithert.md similarity index 97% rename from docs/src/main/mdoc/datatypes/eithert.md rename to docs/datatypes/eithert.md index 606c90a6a0..9cb2437d26 100644 --- a/docs/src/main/mdoc/datatypes/eithert.md +++ b/docs/datatypes/eithert.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "EitherT" -section: "data" -source: "core/src/main/scala/cats/data/EitherT.scala" -scaladoc: "#cats.data.EitherT" ---- # EitherT `Either` can be used for error handling in most situations. However, when diff --git a/docs/src/main/mdoc/datatypes/eval.md b/docs/datatypes/eval.md similarity index 96% rename from docs/src/main/mdoc/datatypes/eval.md rename to docs/datatypes/eval.md index 63f5431aca..a58e835295 100644 --- a/docs/src/main/mdoc/datatypes/eval.md +++ b/docs/datatypes/eval.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Eval" -section: "data" -source: "core/src/main/scala/cats/Eval.scala" -scaladoc: "#cats.Eval" ---- # Eval Eval is a data type for controlling synchronous evaluation. diff --git a/docs/src/main/mdoc/datatypes/freeapplicative.md b/docs/datatypes/freeapplicative.md similarity index 98% rename from docs/src/main/mdoc/datatypes/freeapplicative.md rename to docs/datatypes/freeapplicative.md index 9d9082e18c..01b7fc4e98 100644 --- a/docs/src/main/mdoc/datatypes/freeapplicative.md +++ b/docs/datatypes/freeapplicative.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "FreeApplicatives" -section: "data" -source: "free/src/main/scala/cats/free/FreeApplicative.scala" -scaladoc: "#cats.free.FreeApplicative" ---- # Free Applicative `FreeApplicative`s are similar to `Free` (monads) in that they provide a nice way to represent diff --git a/docs/src/main/mdoc/datatypes/freemonad.md b/docs/datatypes/freemonad.md similarity index 99% rename from docs/src/main/mdoc/datatypes/freemonad.md rename to docs/datatypes/freemonad.md index 9430583d76..6354c2a942 100644 --- a/docs/src/main/mdoc/datatypes/freemonad.md +++ b/docs/datatypes/freemonad.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "FreeMonads" -section: "data" -source: "free/src/main/scala/cats/free/Free.scala" -scaladoc: "#cats.free.Free" ---- - # Free Monad ## What is it? diff --git a/docs/src/main/mdoc/datatypes/functionk.md b/docs/datatypes/functionk.md similarity index 97% rename from docs/src/main/mdoc/datatypes/functionk.md rename to docs/datatypes/functionk.md index a8cbace8ce..27cbda072a 100644 --- a/docs/src/main/mdoc/datatypes/functionk.md +++ b/docs/datatypes/functionk.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "FunctionK" -section: "data" -source: "core/src/main/scala/cats/arrow/FunctionK.scala" -scaladoc: "#cats.arrow.FunctionK" ---- # FunctionK A `FunctionK` transforms values from one first-order-kinded type (a type that takes a single type parameter, such as `List` or `Option`) into another first-order-kinded type. This transformation is diff --git a/docs/src/main/mdoc/datatypes/id.md b/docs/datatypes/id.md similarity index 93% rename from docs/src/main/mdoc/datatypes/id.md rename to docs/datatypes/id.md index 37c9c1c58a..13f451c392 100644 --- a/docs/src/main/mdoc/datatypes/id.md +++ b/docs/datatypes/id.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Id" -section: "data" -source: "core/src/main/scala/cats/package.scala" -scaladoc: "#cats.Id$" ---- # Id The identity monad can be seen as the ambient monad that encodes the diff --git a/docs/src/main/mdoc/datatypes/ior.md b/docs/datatypes/ior.md similarity index 96% rename from docs/src/main/mdoc/datatypes/ior.md rename to docs/datatypes/ior.md index e8ae82b15e..4ca0be7eb0 100644 --- a/docs/src/main/mdoc/datatypes/ior.md +++ b/docs/datatypes/ior.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Ior" -section: "data" -source: "core/src/main/scala/cats/data/Ior.scala" -scaladoc: "#cats.data.Ior" ---- # Ior `Ior` represents an inclusive-or relationship between two data types. diff --git a/docs/src/main/mdoc/datatypes/iort.md b/docs/datatypes/iort.md similarity index 98% rename from docs/src/main/mdoc/datatypes/iort.md rename to docs/datatypes/iort.md index e72af38fe3..4f0554b5a7 100644 --- a/docs/src/main/mdoc/datatypes/iort.md +++ b/docs/datatypes/iort.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "IorT" -section: "data" -source: "core/src/main/scala/cats/data/IorT.scala" -scaladoc: "#cats.data.IorT" ---- # IorT `IorT[F[_], A, B]` is a light wrapper on an `F[Ior[A, B]]`. Similar to diff --git a/docs/src/main/mdoc/datatypes/kleisli.md b/docs/datatypes/kleisli.md similarity index 98% rename from docs/src/main/mdoc/datatypes/kleisli.md rename to docs/datatypes/kleisli.md index e44420cddf..caac96c233 100644 --- a/docs/src/main/mdoc/datatypes/kleisli.md +++ b/docs/datatypes/kleisli.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Kleisli" -section: "data" -source: "core/src/main/scala/cats/data/Kleisli.scala" -scaladoc: "#cats.data.Kleisli" ---- # Kleisli Kleisli enables composition of functions that return a monadic value, for instance an `Option[Int]` or a `Either[String, List[Double]]`, without having functions take an `Option` or `Either` as a parameter, diff --git a/docs/src/main/mdoc/datatypes/nel.md b/docs/datatypes/nel.md similarity index 97% rename from docs/src/main/mdoc/datatypes/nel.md rename to docs/datatypes/nel.md index 1876254d92..bdf1dfdf35 100644 --- a/docs/src/main/mdoc/datatypes/nel.md +++ b/docs/datatypes/nel.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "NonEmptyList" -section: "data" -source: "core/src/main/scala/cats/data/NonEmptyList.scala" -scaladoc: "#cats.data.NonEmptyList" ---- # NonEmptyList ## Motivation diff --git a/docs/src/main/mdoc/datatypes/nested.md b/docs/datatypes/nested.md similarity index 95% rename from docs/src/main/mdoc/datatypes/nested.md rename to docs/datatypes/nested.md index 3d801740f5..5adfc8802b 100644 --- a/docs/src/main/mdoc/datatypes/nested.md +++ b/docs/datatypes/nested.md @@ -1,10 +1,4 @@ ---- -layout: docs -title: "Nested" -section: "data" -source: "core/src/main/scala/cats/data/Nested.scala" -scaladoc: "#cats.data.Nested" ---- +{% laika.title = Nested %} # Motivation diff --git a/docs/src/main/mdoc/datatypes/oneand.md b/docs/datatypes/oneand.md similarity index 84% rename from docs/src/main/mdoc/datatypes/oneand.md rename to docs/datatypes/oneand.md index 0f67ce7c46..9c4dbdc0a2 100644 --- a/docs/src/main/mdoc/datatypes/oneand.md +++ b/docs/datatypes/oneand.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "OneAnd" -section: "data" -source: "core/src/main/scala/cats/data/OneAnd.scala" -scaladoc: "#cats.data.OneAnd" ---- # OneAnd The `OneAnd[F[_],A]` data type represents a single element of type `A` diff --git a/docs/src/main/mdoc/datatypes/optiont.md b/docs/datatypes/optiont.md similarity index 96% rename from docs/src/main/mdoc/datatypes/optiont.md rename to docs/datatypes/optiont.md index 82d0cd36da..53d68d15a8 100644 --- a/docs/src/main/mdoc/datatypes/optiont.md +++ b/docs/datatypes/optiont.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "OptionT" -section: "data" -source: "core/src/main/scala/cats/data/OptionT.scala" -scaladoc: "#cats.data.OptionT" ---- # OptionT `OptionT[F[_], A]` is a light wrapper on an `F[Option[A]]`. Speaking technically, it is a monad transformer for `Option`, but you don't need to know what that means for it to be useful. `OptionT` can be more convenient to work with than using `F[Option[A]]` directly. diff --git a/docs/src/main/mdoc/datatypes/state.md b/docs/datatypes/state.md similarity index 98% rename from docs/src/main/mdoc/datatypes/state.md rename to docs/datatypes/state.md index baca8fff7c..59710a91cb 100644 --- a/docs/src/main/mdoc/datatypes/state.md +++ b/docs/datatypes/state.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "State" -section: "data" -source: "core/src/main/scala/cats/data/StateT.scala" -scaladoc: "#cats.data.StateT" ---- # State `State` is a structure that provides a functional approach to handling application state. `State[S, A]` is basically a function `S => (S, A)`, where `S` is the type that represents your state and `A` is the result the function produces. In addition to returning the result of type `A`, the function returns a new `S` value, which is the updated state. diff --git a/docs/src/main/mdoc/datatypes/validated.md b/docs/datatypes/validated.md similarity index 99% rename from docs/src/main/mdoc/datatypes/validated.md rename to docs/datatypes/validated.md index 4f78b4fc0b..17df801c0e 100644 --- a/docs/src/main/mdoc/datatypes/validated.md +++ b/docs/datatypes/validated.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Validated" -section: "data" -source: "core/src/main/scala/cats/data/Validated.scala" -scaladoc: "#cats.data.Validated" ---- # Validated Imagine you are filling out a web form to signup for an account. You input your username and password and submit. diff --git a/docs/src/main/mdoc/datatypes/writer.md b/docs/datatypes/writer.md similarity index 81% rename from docs/src/main/mdoc/datatypes/writer.md rename to docs/datatypes/writer.md index b935058223..796fb1b85b 100644 --- a/docs/src/main/mdoc/datatypes/writer.md +++ b/docs/datatypes/writer.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Writer" -section: "data" -source: "core/src/main/scala/cats/data/package.scala" -scaladoc: "#cats.data.Writer" ---- # Writer The `Writer[L, A]` datatype represents a computation that produces a @@ -22,16 +15,16 @@ multiple ways. See the [Operations section](#operations) When two functions are composed together, e.g. using `flatMap`, the logs of both functions will be combined using an implicit - [Semigroup](https://typelevel.org/cats/typeclasses/semigroup.html). + [Semigroup](typeclasses/semigroup.html). ## Operations The `Writer` datatype provides a set of functions that are similar to the ones from the -[Monad](https://typelevel.org/cats/typeclasses/monad.html) +[Monad](typeclasses/monad.html) typeclass. In fact, they share the same name and the same signature, but have an additional requirement of a -[`Semigroup[L]`](https://typelevel.org/cats/typeclasses/semigroup.html) +[`Semigroup[L]`](typeclasses/semigroup.html) that allows the log merging. `map` effects only the value, keeping the log side untouched. Plus, here we show `run` @@ -48,7 +41,7 @@ mapExample.run `ap` allows applying a function, wrapped into a Writer. It works exactly like the `Applicative` as expected, but notice how the logs -are combined using the [`Semigroup[String]`](https://typelevel.org/cats/typeclasses/semigroup.html). +are combined using the [`Semigroup[String]`](typeclasses/semigroup.html). ```scala mdoc val apExampleValue = Writer("ap value", 10) @@ -78,13 +71,13 @@ Apart from those, `Writer` comes with some specific functions to manage the log side of the computation: `tell` -: Append a value to the log side. It requires a [`Semigroup[L]`](https://typelevel.org/cats/typeclasses/semigroup.html). +: Append a value to the log side. It requires a [`Semigroup[L]`](typeclasses/semigroup.html). `swap` : Exchange the two values of the `Writer`. `reset` -: Delete the log side. It requires a [`Monoid[L]`](https://typelevel.org/cats/typeclasses/monoid.html) since it uses the `empty` value of the monoid. +: Delete the log side. It requires a [`Monoid[L]`](typeclasses/monoid.html) since it uses the `empty` value of the monoid. `value` : Returns only the value of the `Writer` @@ -130,13 +123,13 @@ type Writer[L, V] = WriterT[Id, L, V] So, all the [Operations](#operations) defined in the previous section are actually coming from the [WriterT -datatype](https://typelevel.org/cats/datatypes/writert.html) +datatype](datatypes/writert.html) -Most of the [`WriterT`](https://typelevel.org/cats/datatypes/writert.html) functions require a -[`Functor[F]`](https://typelevel.org/cats/typeclasses/functor.html) or -[`Monad[F]`](https://typelevel.org/cats/typeclasses/monad.html) +Most of the [`WriterT`](datatypes/writert.html) functions require a +[`Functor[F]`](typeclasses/functor.html) or +[`Monad[F]`](typeclasses/monad.html) instance. However, Cats provides all the necessary instances for the -[`Id`](https://typelevel.org/cats/datatypes/id.html) type, therefore +[`Id`](datatypes/id.html) type, therefore we don't have to worry about them. ## Example diff --git a/docs/src/main/mdoc/datatypes/writert.md b/docs/datatypes/writert.md similarity index 79% rename from docs/src/main/mdoc/datatypes/writert.md rename to docs/datatypes/writert.md index da46e82c71..ec61dedbca 100644 --- a/docs/src/main/mdoc/datatypes/writert.md +++ b/docs/datatypes/writert.md @@ -1,14 +1,7 @@ ---- -layout: docs -title: "WriterT" -section: "data" -source: "core/src/main/scala/cats/data/WriterT.scala" -scaladoc: "#cats.data.WriterT" ---- # WriterT `WriterT[F[_], L, V]` is a type wrapper on an `F[(L, -V)]`. Speaking technically, it is a monad transformer for [`Writer`](https://typelevel.org/cats/datatypes/writer.html), +V)]`. Speaking technically, it is a monad transformer for [`Writer`](datatypes/writer.html), but you don't need to know what that means for it to be useful. @@ -16,8 +9,8 @@ useful. `WriterT` can be more convenient to work with than using `F[Writer[L, V]]` directly, because it exposes operations that allow -you to work with the values of the inner [`Writer`](https://typelevel.org/cats/datatypes/writer.html) (`L` and -`V`) abstracting both the `F` and [`Writer`](https://typelevel.org/cats/datatypes/writer.html). +you to work with the values of the inner [`Writer`](datatypes/writer.html) (`L` and +`V`) abstracting both the `F` and [`Writer`](datatypes/writer.html). For example, `map` allow you to transform the inner `V` value, getting back a `WriterT` that wraps around it. @@ -30,13 +23,13 @@ WriterT[Option, String, Int](Some(("value", 10))).map(x => x * x) Plus, when composing multiple `WriterT` computations, those will be composed following the same behaviour of a -[`Writer`](https://typelevel.org/cats/datatypes/writer.html) and the -generic `F`. Let's see two examples with `Option` and [`Either`](https://typelevel.org/cats/datatypes/either.html): if +[`Writer`](datatypes/writer.html) and the +generic `F`. Let's see two examples with `Option` and [`Either`](datatypes/either.html): if one of the computations has a `None` or a `Left`, the whole computation will return a `None` or a `Left` since the way the two types compose typically behaves that way. Moreover, when the computation succeed, the logging side of the -[`Writer`](https://typelevel.org/cats/datatypes/writer.html)s will be +[`Writer`](datatypes/writer.html)s will be combined. ```scala mdoc:silent @@ -80,18 +73,18 @@ for { Just for completeness, we can have a look at the same example, but with -[`Validated`](https://typelevel.org/cats/datatypes/validated.html) +[`Validated`](datatypes/validated.html) since it as a slightly different behaviour than -[`Either`](https://typelevel.org/cats/datatypes/either.html). Instead +[`Either`](datatypes/either.html). Instead of short-circuiting when the first error is encountered, -[`Validated`](https://typelevel.org/cats/datatypes/validated.html) +[`Validated`](datatypes/validated.html) will accumulate all the errors. In the following example, you can see how this behaviour is respected when -[`Validated`](https://typelevel.org/cats/datatypes/validated.html) is +[`Validated`](datatypes/validated.html) is wrapped as the `F` type of a `WriterT`. In addition, notice how `flatMap` and for comprehension can't be used in this case, since -[`Validated`](https://typelevel.org/cats/datatypes/validated.html) -only extends [`Applicative`](https://typelevel.org/cats/typeclasses/applicative.html), but not [`Monad`](https://typelevel.org/cats/typeclasses/monad.html). +[`Validated`](datatypes/validated.html) +only extends [`Applicative`](typeclasses/applicative.html), but not [`Monad`](typeclasses/monad.html). ```scala mdoc:silent import cats.data.Validated @@ -138,9 +131,9 @@ type starting from the full wrapped value. `liftF[F[_], L, V](fv: F[V])(implicit monoidL: Monoid[L], F: Applicative[F]): WriterT[F, L, V]` : This function allows you to build the datatype starting from the value `V` wrapped into an `F`. Notice how it requires: -* [`Monoid[L]`](https://typelevel.org/cats/typeclasses/monoid.html), since it uses the `empty` value from the typeclass. +* [`Monoid[L]`](typeclasses/monoid.html), since it uses the `empty` value from the typeclass. to fill the `L` value not specified in the input. -* [`Applicative[F]`](https://typelevel.org/cats/typeclasses/applicative.html) to modify the inner value. +* [`Applicative[F]`](typeclasses/applicative.html) to modify the inner value. ```scala mdoc:nest import cats.instances.option._ @@ -151,8 +144,8 @@ to fill the `L` value not specified in the input. ``` `put[F[_], L, V](v: V)(l: L)(implicit applicativeF: Applicative[F]): WriterT[F, L, V]` -: As soon as there is an [`Applicative`](https://typelevel.org/cats/typeclasses/applicative.html) instance of `F`, this function -creates the datatype starting from the inner [`Writer`](https://typelevel.org/cats/datatypes/writer.html)'s values. +: As soon as there is an [`Applicative`](typeclasses/applicative.html) instance of `F`, this function +creates the datatype starting from the inner [`Writer`](datatypes/writer.html)'s values. ```scala mdoc:nest WriterT.put[Option, String, Int](123)("initial value") @@ -168,14 +161,14 @@ creates the datatype starting from the inner [`Writer`](https://typelevel.org/ca ## Operations In the [Writer -definition](https://typelevel.org/cats/datatypes/writer.html#definition) +definition](datatypes/writer.html#definition) section, we showed how it is actually a `WriterT`. Therefore, all the operations described into [Writer -operations](https://typelevel.org/cats/datatypes/writer.html#operations) +operations](datatypes/writer.html#operations) are valid for `WriterT` as well. The only aspect we want to remark here is the following sentence from -[`Writer`](https://typelevel.org/cats/datatypes/writer.html)'s page: +[`Writer`](datatypes/writer.html)'s page: > Most of the `WriterT` functions require a `Functor[F]` or > `Monad[F]` instance. However, Cats provides all the necessary diff --git a/docs/directory.conf b/docs/directory.conf new file mode 100644 index 0000000000..8325f18557 --- /dev/null +++ b/docs/directory.conf @@ -0,0 +1,17 @@ +laika.navigationOrder = [ + index.md + typeclasses.md + datatypes.md + algebra.md + motivations.md + resources_for_learners.md + jump_start_guide.md + faq.md + contributing.md + colophon.md + nomenclature.md + guidelines.md + typelevelEcosystem.md + typeclasses + datatypes +] \ No newline at end of file diff --git a/docs/src/main/mdoc/faq.md b/docs/faq.md similarity index 77% rename from docs/src/main/mdoc/faq.md rename to docs/faq.md index 495bba0c1c..c2dc3834e0 100644 --- a/docs/src/main/mdoc/faq.md +++ b/docs/faq.md @@ -1,35 +1,13 @@ ---- -layout: page -title: "FAQ" -section: "faq" -position: 40 ---- +{% laika.title = FAQ %} # Frequently Asked Questions -## Questions - * [What imports do I need?](#what-imports) - * [I am new to pure functional programming, what quick wins can I get from Cats?](#quick-wins) - * [What is the difference between Cats and Scalaz?](#diff-scalaz) - * [Where is right-biased `Either`?](#either) - * [Why is the compiler having trouble with types with more than one type parameter?](#si-2712) - * [Why can't the compiler find implicit instances for Future?](#future-instances) - * [Where are implicit instances for `Seq`](seq-instances) - * [Why is some example code not compiling for me?](#example-compile) - * [How can I turn my List of `` into a `` of a list?](#traverse) - * [Where is `ListT`?](#listt) - * [Where are `Applicative`s for monad transformers?](#applicative-monad-transformers) - * [Where is `IO`/`Task`?](#task) - * [What does `@typeclass` mean?](#simulacrum) - * [What do types like `?` and `λ` mean?](#kind-projector) - * [What is `tailRecM`?](#tailrecm) - * [What does this symbol mean?](#symbol) - * [How can I test instances against their type classes' laws?](#law-testing) - * [How can I help?](#contributing) - * [Why aren't monad transformers like `OptionT` and `EitherT` covariant like `Option` and `Either`?](#monad-transformer-variance) - * [How to try Cats in a REPL?](#ammonite) - -## What imports do I need? +@:navigationTree { + entries = [ { target = "faq.md", depth = 2 } ] +} + + +## What imports do I need? The easiest approach to Cats imports is to import everything that's commonly needed: @@ -39,19 +17,19 @@ import cats.data._ import cats.syntax.all._ ``` -This should be all that you need, but if you'd like to learn more about the details of imports than you can check out the [import guide](typeclasses/imports.html). +This should be all that you need, but if you'd like to learn more about the details of imports than you can check out the [import guide](typeclasses/imports.md). -## I am new to pure functional programming, what quick wins can I get from Cats? +## I am new to pure functional programming, what quick wins can I get from Cats? -Please refer to the [jump start guide]({{ site.baseurl }}/jump_start_guide.html). +Please refer to the [jump start guide](jump_start_guide.md). -## What is the difference between Cats and Scalaz? +## What is the difference between Cats and Scalaz? Cats and [Scalaz](https://github.com/scalaz/scalaz) have the same goal: to facilitate pure functional programming in Scala applications. However the underlying core strategy is different; Scalaz took the approach of trying to provide a single batteries-included *standard library* for FP that powers the Scala applications. Cats, on the other hand, aims to help build an [ecosystem](/cats/#ecosystem) of pure FP libraries by providing a solid and stable foundation; these libraries can have their own styles and personalities, competing with each other, while at the same time playing nice. It is through this ecosystem of FP libraries (cats included) that Scala applications can be powered with "FP awesome-ness" and beyond by picking whatever best fit their needs. Based on this core strategy, Cats takes a [modular](/cats/motivations#modularity) approach and focuses on providing core, [binary compatible](/cats/#binary-compatibility-and-versioning), [approachable](/cats/motivations#approachability) and [efficient](/cats/motivations#efficiency) abstractions. It provides a welcoming and supportive environment for the [user community](https://discord.gg/XF3CXcMzqD) governed by the [Scala Code of Conduct](https://www.scala-lang.org/conduct/). It also takes great effort in supplying a comprehensive and beginner-friendly [documentation](/cats/#documentation). -## Where is right-biased Either? +## Where is right-biased Either? Up through Cats 0.7.x we had `cats.data.Xor`, which was effectively `scala.util.Either`, but right-biased by default and with a bunch of useful combinators around it. In Scala 2.12.x `Either` [became right-biased](https://github.com/scala/scala/pull/5135) so we revisited the use of `Xor` and @@ -61,36 +39,36 @@ fill in the gaps in the `scala.util.Either` API via This syntax and the type class instances for `Either` can be imported using `cats.implicits._`, which will also bring in syntactic enrichment and instances for other standard library types, or you can import them individually with `cats.syntax.either._` and `cats.instances.either._`. -There are a few minor mismatches between `Xor` and `Either`. For example, in some cases you may need to specify a type parameter for an enrichment method on `Either` (such as `leftMap`) even though it was properly inferred for `Xor`. See the [`Either` section of this guide](http://typelevel.org/cats/datatypes/either.html#either-in-the-small-either-in-the-large) for more information about these issues. +There are a few minor mismatches between `Xor` and `Either`. For example, in some cases you may need to specify a type parameter for an enrichment method on `Either` (such as `leftMap`) even though it was properly inferred for `Xor`. See the [`Either` section of this guide](datatypes/either.md#either-in-the-small-either-in-the-large) for more information about these issues. Similarly, `cats.data.XorT` has been replaced with `cats.data.EitherT`, although since this is a type defined in Cats, you don't need to import syntax or instances for it (although you may need imports for the underlying monad). -## Why is the compiler having trouble with types with more than one type parameter? +## Why is the compiler having trouble with types with more than one type parameter? -When you encounter a situation where the same code works fine with a type with one type parameter, e.g. List[A], but doesn't work with types with more than one, e.g. Either[A, B], you probably hit [SI-2712](https://issues.scala-lang.org/browse/SI-2712). Without going into the details, it's highly recommended to enable a partial SI-2712 fix in your project. The easiest way to achieve that is through this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification). +When you encounter a situation where the same code works fine with a type with one type parameter, e.g. `List[A]`, but doesn't work with types with more than one, e.g. `Either[A, B]`, you probably hit [SI-2712](https://issues.scala-lang.org/browse/SI-2712). Without going into the details, it's highly recommended to enable a partial SI-2712 fix in your project. The easiest way to achieve that is through this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification). Cats used to provide mitigation to this issue semi-transparently, but given the fact that the fix is now mainstream, we decided to drop that mitigation machinery in favor of reducing the complexity. See this [issue](https://github.com/typelevel/cats/issues/1073) for details. -## Why is some example code not compiling for me? +## Why is some example code not compiling for me? A portion of example code requires either the [Kind-projector](https://github.com/typelevel/kind-projector) compiler plugin or partial unification turned on in scalac. The easiest way to turn partial unification on is through this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification). -## Why can't the compiler find implicit instances for Future? +## Why can't the compiler find implicit instances for Future? -If you have already followed the [imports advice](#what-imports) but are still getting error messages like `could not find implicit value for parameter e: cats.Monad[scala.concurrent.Future]` or `value |+| is not a member of scala.concurrent.Future[Int]`, then make sure that you have an implicit `scala.concurrent.ExecutionContext` in scope. The easiest way to do this is to `import scala.concurrent.ExecutionContext.Implicits.global`, but note that you may want to use a different execution context for your production application. +If you have already followed the [imports advice](#what-imports-do-i-need) but are still getting error messages like `could not find implicit value for parameter e: cats.Monad[scala.concurrent.Future]` or `value |+| is not a member of scala.concurrent.Future[Int]`, then make sure that you have an implicit `scala.concurrent.ExecutionContext` in scope. The easiest way to do this is to `import scala.concurrent.ExecutionContext.Implicits.global`, but note that you may want to use a different execution context for your production application. -## Where are implicit instances for `Seq`? +## Where are implicit instances for `Seq`? As of `cats-2.3`, instances for `collection.immutable.Seq` are provided by cats. Mind that, up to `scala-2.12`, `Seq` was an alias for `collection.Seq` and lawful instances can't be provided for it due to its potential mutability. In `scala-2.13`, `Seq` was changed to `collection.immutable.Seq` which greatly improves `Seq`'s interoperability with cats. -## How can I turn my List of `` into a `` of a list? +## How can I turn my List of `` into a `` of a list? -It's really common to have a `List` of values with types like `Option`, `Either`, or `Validated` that you would like to turn "inside out" into an `Option` (or `Either` or `Validated`) of a `List`. The `sequence` and `traverse` methods are _really_ handy for this. You can read more about them in the [Traverse documentation]({{ site.baseurl }}/typeclasses/traverse.html). +It's really common to have a `List` of values with types like `Option`, `Either`, or `Validated` that you would like to turn "inside out" into an `Option` (or `Either` or `Validated`) of a `List`. The `sequence` and `traverse` methods are _really_ handy for this. You can read more about them in the [Traverse documentation](typeclasses/traverse.md). -## Where is ListT? +## Where is ListT? -There are monad transformers for various types, such as [OptionT]({{ site.baseurl }}/datatypes/optiont.html), so people often wonder why there isn't a `ListT`. For example, in the following example, people might reach for `ListT` to simplify making nested `map` and `exists` calls: +There are monad transformers for various types, such as [OptionT](datatypes/optiont.md), so people often wonder why there isn't a `ListT`. For example, in the following example, people might reach for `ListT` to simplify making nested `map` and `exists` calls: ```scala mdoc:reset:silent val l: Option[List[Int]] = Some(List(1, 2, 3, 4, 5)) @@ -130,13 +108,13 @@ def even(i: Int): ErrorsOr[Int] = if (i % 2 == 0) i.validNel else s"$i is odd".i nl.traverse(even) ``` -## Where are `Applicative`s for monad transformers? +## Where are `Applicative`s for monad transformers? -An `Applicative` instance for `OptionT[F, *]`/`EitherT[F, E, *]`, built without a corresponding `Monad` instance for `F`, would be unlawful, so it's not included. See [the guidelines](https://typelevel.org/cats/guidelines.html#applicative-monad-transformers) for a more detailed explanation. +An `Applicative` instance for `OptionT[F, *]`/`EitherT[F, E, *]`, built without a corresponding `Monad` instance for `F`, would be unlawful, so it's not included. See [the guidelines](guidelines.html#applicative-monad-transformers) for a more detailed explanation. As an alternative, using `.toNested` on the monad transformer is recommended, although its `ap` will still be inconsistent with the Monad instance's.`. -## Where is IO/Task? +## Where is IO/Task? In purely functional programming, a monadic `IO` or `Task` type is often used to handle side effects such as file/network IO. In some languages and frameworks, such a type also serves as the primary abstraction through which parallelism is achieved. Nearly every real-world purely functional application or service is going to require such a data type, and this gives rise to an obvious question: why doesn't Cats include such a type? @@ -144,23 +122,23 @@ The answer is that Cats *does* include an `IO`, it just isn't included in the co However, we acknowledge that this type may not meet everyone's needs. The cats-effect project characterizes the space of side-effect-capturing data types with a set of typeclasses (deriving from `cats.Monad`), and so all such data types are, broadly-speaking, mutually compatible and interchangeable in many generic contexts. For example, [Monix](https://monix.io) provides support for IO, concurrency, and streaming and integrates with the cats-effect type classes. -It may be worth keeping in mind that `IO` and `Task` are pretty blunt instruments (they are essentially the `Any` of side effect management), and you may want to narrow the scope of your effects throughout most of your application. The [free monad]({{ site.baseurl }}/datatypes/freemonad.html) documentation describes a way to abstractly define controlled effects and interpret them into a type such as `IO` or `Task` as late as possible. As more of your code becomes pure through these controlled effects the less it matters which type you end up choosing to represent your side effects. +It may be worth keeping in mind that `IO` and `Task` are pretty blunt instruments (they are essentially the `Any` of side effect management), and you may want to narrow the scope of your effects throughout most of your application. The [free monad](datatypes/freemonad.md) documentation describes a way to abstractly define controlled effects and interpret them into a type such as `IO` or `Task` as late as possible. As more of your code becomes pure through these controlled effects the less it matters which type you end up choosing to represent your side effects. -## What does `@typeclass` mean? +## What does `@typeclass` mean? Cats defines and implements numerous type classes. Unfortunately, encoding these type classes in Scala can incur a large amount of boilerplate. To address this, [Simulacrum](https://github.com/typelevel/simulacrum) introduces `@typeclass`, a macro annotation which generates a lot of this boilerplate. This elevates type classes to a first class construct and increases the legibility and maintainability of the code. Use of simulacrum also ensures consistency in how the type classes are encoded across a project. Cats uses simulacrum wherever possible to encode type classes, and you can read more about it at the [project page](https://github.com/typelevel/simulacrum). Note that the one area where simulacrum is intentionally not used is in the `cats-kernel` module. The `cats-kernel` module is intended to be a shared dependency for a number of projects, and as such, it is important that it is both lightweight and very stable from a binary compatibility perspective. At some point there may be a transition from simulacrum to [typeclassic](https://github.com/typelevel/typeclassic), and the binary compatibility of moving between simulacrum and typeclassic is unclear at this point. Avoiding the dependency on simulacrum in `cats-kernel`, provides insulation against any potential binary compatibility problems in such a transition. -## What do types like `?` and `λ` mean? +## What do types like `?` and `λ` mean? -Cats defines a wealth of type classes and type class instances. For a number of the type class and instance combinations, there is a mismatch between the type parameter requirements of the type class and the type parameter requirements of the data type for which the instance is being defined. For example, the [Either]({{ site.baseurl }}/datatypes/either.html) data type is a type constructor with two type parameters. We would like to be able to define a [Monad]({{ site.baseurl }}/typeclasses/monad.html) for `Either`, but the `Monad` type class operates on type constructors having only one type parameter. +Cats defines a wealth of type classes and type class instances. For a number of the type class and instance combinations, there is a mismatch between the type parameter requirements of the type class and the type parameter requirements of the data type for which the instance is being defined. For example, the [Either](datatypes/either.md) data type is a type constructor with two type parameters. We would like to be able to define a [Monad](typeclasses/monad.md) for `Either`, but the `Monad` type class operates on type constructors having only one type parameter. -**Enter type lambdas!** Type lambdas provide a mechanism to allow one or more of the type parameters for a particular type constructor to be fixed. In the case of `Either` then, when defining a `Monad` for `Either`, we want to fix one of the type parameters at the point where a `Monad` instance is summoned, so that the type parameters line up. As `Either` is right biased, a type lambda can be used to fix the left type parameter and allow the right type parameter to continue to vary when `Either` is treated as a `Monad`. The right biased nature of `Either` is discussed further in the [`Either` documentation]({{ site.baseurl }}/datatypes/either.html). +**Enter type lambdas!** Type lambdas provide a mechanism to allow one or more of the type parameters for a particular type constructor to be fixed. In the case of `Either` then, when defining a `Monad` for `Either`, we want to fix one of the type parameters at the point where a `Monad` instance is summoned, so that the type parameters line up. As `Either` is right biased, a type lambda can be used to fix the left type parameter and allow the right type parameter to continue to vary when `Either` is treated as a `Monad`. The right biased nature of `Either` is discussed further in the [`Either` documentation](datatypes/either.html). **Enter [kind-projector](https://github.com/typelevel/kind-projector)!** kind-projector is a compiler plugin which provides a convenient syntax for dealing with type lambdas. The symbols `?` and `λ` are treated specially by kind-projector, and expanded into the more verbose definitions that would be required were it not to be used. You can read more about kind-projector at the [project page](https://github.com/typelevel/kind-projector). -## What is `tailRecM`? +## What is `tailRecM`? The `FlatMap` type class has a `tailRecM` method with the following signature: @@ -215,7 +193,7 @@ If you're having trouble figuring out how to implement `tailRecM` lawfully, you In some cases you may decide that providing a lawful `tailRecM` may be impractical or even impossible (if so we'd like to hear about it). For these cases we provide a way of testing all of the monad laws _except_ for the stack safety of `tailRecM`: just replace `MonadTests[F].monad[A, B, C]` in your tests with `MonadTests[F].stackUnsafeMonad[A, B, C]`. -## What does this symbol mean? +## What does this symbol mean? Below is a list of symbols used in Cats. @@ -252,20 +230,20 @@ All other symbols can be imported with `import cats.implicits._` | `fa << fb` (Deprecated) | product left | | `FlatMap[F[_]]` | `productL(fa: F[A])(fb: F[B]): F[A]` | -## How can I test instances against their type classes' laws? +## How can I test instances against their type classes' laws? -You can find more information [here](typeclasses/lawtesting.html). +You can find more information [here](typeclasses/lawtesting.md). -## How can I help? +## How can I help? The Сats community welcomes and encourages contributions, even if you are completely new to Сats and functional programming. Here are a few ways to help out: - Find an undocumented method and write a ScalaDoc entry for it. See [Arrow.scala](https://github.com/typelevel/cats/blob/main/core/src/main/scala/cats/arrow/Arrow.scala) for some examples of ScalaDoc entries that use [sbt-doctest](https://github.com/tkawachi/sbt-doctest). - Find an [open issue](https://github.com/typelevel/cats/issues?q=is%3Aopen+is%3Aissue+label%3Aready), leave a comment on it to let people know you are working on it, and submit a pull request. If you are new to Сats, you may want to look for items with the [low-hanging-fruit](https://github.com/typelevel/cats/issues?q=is%3Aopen+is%3Aissue+label%3A%22low-hanging+fruit%22) label. -See the [contributing guide]({{ site.baseurl }}/contributing.html) for more information. +See the [contributing guide](contributing.md) for more information. -## How to try Cats in a REPL? +## How to try Cats in a REPL? The easiest way is probably using [Ammonite-REPL](http://ammonite.io/). Install it following the instructions there. Then in the amm console you can type in ```scala @@ -274,6 +252,6 @@ import $ivy.`org.typelevel::cats-core:2.1.1`, cats._, cats.data._, cats.implicit ``` Or if you want, you can add these lines to `~/.ammonite/predef.sc` so that they are enabled every ammonite session. -## Why aren't monad transformers like `OptionT` and `EitherT` covariant like `Option` and `Either`? +## Why aren't monad transformers like `OptionT` and `EitherT` covariant like `Option` and `Either`? Please see [Variance of Monad Transformers](https://typelevel.org/blog/2018/09/29/monad-transformer-variance.html) on the Typelevel blog. diff --git a/docs/src/main/mdoc/guidelines.md b/docs/guidelines.md similarity index 100% rename from docs/src/main/mdoc/guidelines.md rename to docs/guidelines.md diff --git a/docs/src/main/resources/microsite/img/cats-badge-big.png b/docs/img/cats-badge-big.png similarity index 100% rename from docs/src/main/resources/microsite/img/cats-badge-big.png rename to docs/img/cats-badge-big.png diff --git a/docs/src/main/resources/microsite/img/cats-badge-normal.png b/docs/img/cats-badge-normal.png similarity index 100% rename from docs/src/main/resources/microsite/img/cats-badge-normal.png rename to docs/img/cats-badge-normal.png diff --git a/docs/src/main/resources/microsite/img/cats-badge-tiny.png b/docs/img/cats-badge-tiny.png similarity index 100% rename from docs/src/main/resources/microsite/img/cats-badge-tiny.png rename to docs/img/cats-badge-tiny.png diff --git a/docs/src/main/resources/microsite/img/cats-badge.svg b/docs/img/cats-badge.svg similarity index 100% rename from docs/src/main/resources/microsite/img/cats-badge.svg rename to docs/img/cats-badge.svg diff --git a/docs/src/main/resources/microsite/img/cats-logo.png b/docs/img/cats-logo.png similarity index 100% rename from docs/src/main/resources/microsite/img/cats-logo.png rename to docs/img/cats-logo.png diff --git a/docs/src/main/resources/microsite/img/cats-logo.svg b/docs/img/cats-logo.svg similarity index 100% rename from docs/src/main/resources/microsite/img/cats-logo.svg rename to docs/img/cats-logo.svg diff --git a/docs/src/main/resources/microsite/img/cats2.png b/docs/img/cats2.png similarity index 100% rename from docs/src/main/resources/microsite/img/cats2.png rename to docs/img/cats2.png diff --git a/docs/src/main/resources/microsite/img/donate-button.png b/docs/img/donate-button.png similarity index 100% rename from docs/src/main/resources/microsite/img/donate-button.png rename to docs/img/donate-button.png diff --git a/docs/src/main/resources/microsite/img/favicon.png b/docs/img/favicon.png similarity index 100% rename from docs/src/main/resources/microsite/img/favicon.png rename to docs/img/favicon.png diff --git a/docs/src/main/resources/microsite/img/jumbotron_pattern.png b/docs/img/jumbotron_pattern.png similarity index 100% rename from docs/src/main/resources/microsite/img/jumbotron_pattern.png rename to docs/img/jumbotron_pattern.png diff --git a/docs/src/main/resources/microsite/img/jumbotron_pattern2x.png b/docs/img/jumbotron_pattern2x.png similarity index 100% rename from docs/src/main/resources/microsite/img/jumbotron_pattern2x.png rename to docs/img/jumbotron_pattern2x.png diff --git a/docs/src/main/resources/microsite/img/missing-avatar.svg b/docs/img/missing-avatar.svg similarity index 100% rename from docs/src/main/resources/microsite/img/missing-avatar.svg rename to docs/img/missing-avatar.svg diff --git a/docs/src/main/resources/microsite/img/navbar_brand.png b/docs/img/navbar_brand.png similarity index 100% rename from docs/src/main/resources/microsite/img/navbar_brand.png rename to docs/img/navbar_brand.png diff --git a/docs/src/main/resources/microsite/img/navbar_brand2x.png b/docs/img/navbar_brand2x.png similarity index 100% rename from docs/src/main/resources/microsite/img/navbar_brand2x.png rename to docs/img/navbar_brand2x.png diff --git a/docs/src/main/resources/microsite/img/parallel.png b/docs/img/parallel.png similarity index 100% rename from docs/src/main/resources/microsite/img/parallel.png rename to docs/img/parallel.png diff --git a/docs/src/main/resources/microsite/img/poster.png b/docs/img/poster.png similarity index 100% rename from docs/src/main/resources/microsite/img/poster.png rename to docs/img/poster.png diff --git a/docs/src/main/resources/microsite/img/sidebar_brand.png b/docs/img/sidebar_brand.png similarity index 100% rename from docs/src/main/resources/microsite/img/sidebar_brand.png rename to docs/img/sidebar_brand.png diff --git a/docs/src/main/resources/microsite/img/sidebar_brand2x.png b/docs/img/sidebar_brand2x.png similarity index 100% rename from docs/src/main/resources/microsite/img/sidebar_brand2x.png rename to docs/img/sidebar_brand2x.png diff --git a/docs/src/main/resources/microsite/img/sponsors/47_degree.png b/docs/img/sponsors/47_degree.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/47_degree.png rename to docs/img/sponsors/47_degree.png diff --git a/docs/src/main/resources/microsite/img/sponsors/commercetools.png b/docs/img/sponsors/commercetools.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/commercetools.png rename to docs/img/sponsors/commercetools.png diff --git a/docs/src/main/resources/microsite/img/sponsors/ebiznext.png b/docs/img/sponsors/ebiznext.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/ebiznext.png rename to docs/img/sponsors/ebiznext.png diff --git a/docs/src/main/resources/microsite/img/sponsors/evolution_gaming_engineering.png b/docs/img/sponsors/evolution_gaming_engineering.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/evolution_gaming_engineering.png rename to docs/img/sponsors/evolution_gaming_engineering.png diff --git a/docs/src/main/resources/microsite/img/sponsors/inner-product.png b/docs/img/sponsors/inner-product.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/inner-product.png rename to docs/img/sponsors/inner-product.png diff --git a/docs/src/main/resources/microsite/img/sponsors/iterators.png b/docs/img/sponsors/iterators.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/iterators.png rename to docs/img/sponsors/iterators.png diff --git a/docs/src/main/resources/microsite/img/sponsors/triplequote.png b/docs/img/sponsors/triplequote.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/triplequote.png rename to docs/img/sponsors/triplequote.png diff --git a/docs/src/main/resources/microsite/img/sponsors/underscore.png b/docs/img/sponsors/underscore.png similarity index 100% rename from docs/src/main/resources/microsite/img/sponsors/underscore.png rename to docs/img/sponsors/underscore.png diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000000..32d46ee883 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/src/main/resources/microsite/js/sponsors.js b/docs/js/sponsors.js similarity index 85% rename from docs/src/main/resources/microsite/js/sponsors.js rename to docs/js/sponsors.js index 13daa94360..c64d9e270c 100644 --- a/docs/src/main/resources/microsite/js/sponsors.js +++ b/docs/js/sponsors.js @@ -60,39 +60,39 @@ sponsors(); addSponsor('gold-sponsors', { name: "47 Degrees", website: "https://47deg.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/47_degree.png" + imageUrl: "img/sponsors/47_degree.png" }); addSponsor('gold-sponsors', { name: "Iterators", website: "https://iteratorshq.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/iterators.png", + imageUrl: "img/sponsors/iterators.png", marginBottom: 20 }); addSponsor('gold-sponsors', { name: "Triplequote", website: "https://triplequote.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/triplequote.png", + imageUrl: "img/sponsors/triplequote.png", marginBottom: 20 }); addSponsor('gold-sponsors', { name: "Underscore", website: "https://underscore.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/underscore.png", + imageUrl: "img/sponsors/underscore.png", marginBottom: 10 }); addSponsor('silver-sponsors', { name: "Ebiznext", website: "https://ebiznext.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/ebiznext.png", + imageUrl: "img/sponsors/ebiznext.png", marginBottom: 10 }); addSponsor('silver-sponsors', { name: "Inner Product", website: "https://inner-product.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/inner-product.png" + imageUrl: "img/sponsors/inner-product.png" }); addSponsor('silver-sponsors', { name: "Evolution Gaming Engineering", website: "https://evolutiongaming.com", - imageUrl: "https://typelevel.org/cats/img/sponsors/evolution_gaming_engineering.png" + imageUrl: "img/sponsors/evolution_gaming_engineering.png" }); diff --git a/docs/src/main/mdoc/jump_start_guide.md b/docs/jump_start_guide.md similarity index 96% rename from docs/src/main/mdoc/jump_start_guide.md rename to docs/jump_start_guide.md index a00c8aed35..d0cf8c07a1 100644 --- a/docs/src/main/mdoc/jump_start_guide.md +++ b/docs/jump_start_guide.md @@ -1,8 +1,4 @@ ---- -layout: page -title: "Jump Start Guide" -section: "jump_start_guide" ---- +{% laika.title = Jump Start Guide %} # Introduction @@ -126,8 +122,8 @@ def processAsync: Future[ProcessingResult] = { } ``` -By default the implicit instances (namely, [`Functor[Future]`](http://typelevel.org/cats/api/cats/Functor.html) and -[`Semigroupal[Future]`](https://typelevel.org/cats/api/cats/Semigroupal.html)) required for `mapN` to work properly are always visible. They are present in the respective companion objects of the instances and hence we do not need to import them explicitly. +By default the implicit instances (namely, [`Functor[Future]`](api/cats/Functor.html) and +[`Semigroupal[Future]`](api/cats/Semigroupal.html)) required for `mapN` to work properly are always visible. They are present in the respective companion objects of the instances and hence we do not need to import them explicitly. This above idea can be expressed even shorter, just: @@ -228,7 +224,7 @@ and that solves our problem for good. ## `import cats.data.OptionT` -An instance of [`OptionT[F, A]`](http://typelevel.org/cats/api/cats/data/EitherT.html) can be thought of as a wrapper over `F[Option[A]]` +An instance of [`OptionT[F, A]`](api/cats/data/EitherT.html) can be thought of as a wrapper over `F[Option[A]]` which adds a couple of useful methods specific to nested types that aren't available in `F` or `Option` itself. Most typically, your `F` will be `Future` (or sometimes slick's `DBIO`, but this requires having an implementation of Cats type classes like `Functor` or `Monad` for `DBIO`). Wrappers such as `OptionT` are generally known as _monad transformers_. @@ -315,7 +311,7 @@ Otherwise, if the result of all three calls contains `Some`, the final outcome w ## `import cats.data.EitherT` -[`EitherT[F, A, B]`](http://typelevel.org/cats/api/cats/data/EitherT.html) is the monad transformer for `Either` — you can think of it as a wrapper over a `F[Either[A, B]]` value. +[`EitherT[F, A, B]`](api/cats/data/EitherT.html) is the monad transformer for `Either` — you can think of it as a wrapper over a `F[Either[A, B]]` value. Just as in the above section, I simplified the method headers, skipping type parameters or their context bounds and lower bounds. diff --git a/docs/src/main/mdoc/motivations.md b/docs/motivations.md similarity index 86% rename from docs/src/main/mdoc/motivations.md rename to docs/motivations.md index 3146fcc855..640ff0bbc1 100644 --- a/docs/src/main/mdoc/motivations.md +++ b/docs/motivations.md @@ -1,10 +1,4 @@ ---- -layout: page -title: "Motivations" -section: "motivations" -position: 25 ---- - +{% laika.title = Motivations %} #### Approachability @@ -16,12 +10,12 @@ in trying to teach others about these concepts, and trying to make decisions which will help ease the process of getting acquainted to the library for a newcomer. If you have any feedback for us in this regard, we would love to hear from you. See the [Contributing -page](contributing.html) to find out ways to give us feedback. +page](contributing.md) to find out ways to give us feedback. #### Modularity We are trying to make the library modular. It will have a tight -core which will contain only the [type classes](typeclasses.html), +core which will contain only the [type classes](typeclasses.md), the bare minimum of data structures that are needed to support them, and type class instances for those data structures and standard library types. @@ -37,7 +31,7 @@ how the software can be used. Writing documentation is a huge part of developing software, and one that is often neglected. It is also a very easy way to get started -with [contributing](contributing.html) to the project. +with [contributing](contributing.md) to the project. #### Efficiency diff --git a/docs/src/main/mdoc/nomenclature.md b/docs/nomenclature.md similarity index 98% rename from docs/src/main/mdoc/nomenclature.md rename to docs/nomenclature.md index d4c8f31a82..d6fb8051ea 100644 --- a/docs/src/main/mdoc/nomenclature.md +++ b/docs/nomenclature.md @@ -1,9 +1,4 @@ ---- -layout: page -title: "Glossary" -section: "Glossary" -position: 60 ---- +# Glossary This is a catalogue of the major functions, type classes, and data types in `Cats`. It serves as a bird's-eye view of each class capabilities. It is also intended as a go-to reference for `Cats` users, who may not recall the answer to questions like these: @@ -283,6 +278,6 @@ Because `Сats` is a Scala library and Scala has many knobs and switches, the ac - For functions defined as method of the typeclass trait, we ignore the receiver object. - We ignore implicit parameters that represent type-class constraints; and write them on a side column instead. - We use `A => B` for both `Function1[A, B]` and `PartialFunction[A, B]` parameters, without distinction. We add a side note when one is a `PartialFunction`. -- Some functions are defined through the [Partially Applied Type Params](http://typelevel.org/cats/guidelines.html#partially-applied-type-params) pattern. We ignore this. +- Some functions are defined through the [Partially Applied Type Params](guidelines.html#partially-applied-type-params) pattern. We ignore this. - We ignore the distinction between by-name and by-value input parameters. We use the notation `=> A`, without parameters, to indicate constant functions. - We ignore Scala variance annotations. We also ignore extra type parameters, which in some methods are added with a subtype-constraint, (e.g. `B >: A`). These are usually meant for flexibility, but we replace each one by its bound. diff --git a/docs/src/main/mdoc/resources_for_learners.md b/docs/resources_for_learners.md similarity index 96% rename from docs/src/main/mdoc/resources_for_learners.md rename to docs/resources_for_learners.md index d22c8340b8..cfd6d49ac6 100644 --- a/docs/src/main/mdoc/resources_for_learners.md +++ b/docs/resources_for_learners.md @@ -1,9 +1,5 @@ ---- -layout: page -title: "Resources for Learners" -section: "resources_for_learners" -position: 30 ---- +{% laika.title = Resources for Learners %} + # Books * [Functional Programming in Scala](https://www.manning.com/books/functional-programming-in-scala) by Paul Chiusano and Rúnar Bjarnason - While this book does not diff --git a/docs/src/main/mdoc/datatypes.md b/docs/src/main/mdoc/datatypes.md deleted file mode 100644 index 0d493cea49..0000000000 --- a/docs/src/main/mdoc/datatypes.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: docs -title: "Data Types" -section: "data" -position: 20 ---- -# Data Types - -{% for x in site.pages %} - {% if x.section == 'data' and x.title != page.title %} -- [{{x.title}}]({{site.baseurl}}{{x.url}}) - {% endif %} -{% endfor %} diff --git a/docs/src/main/mdoc/typeclasses.md b/docs/src/main/mdoc/typeclasses.md deleted file mode 100644 index 8a5ab9b81e..0000000000 --- a/docs/src/main/mdoc/typeclasses.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: docs -title: "Type Classes" -section: "typeclasses" -position: 10 ---- -{% include_relative typeclasses/typeclasses.md %} diff --git a/docs/src/main/resources/microsite/css/override.css b/docs/src/main/resources/microsite/css/override.css deleted file mode 100644 index 5a539f14f7..0000000000 --- a/docs/src/main/resources/microsite/css/override.css +++ /dev/null @@ -1,3 +0,0 @@ -.technologies { - display: none; -} \ No newline at end of file diff --git a/docs/src/main/resources/microsite/data/menu.yml b/docs/src/main/resources/microsite/data/menu.yml deleted file mode 100644 index b967b9553d..0000000000 --- a/docs/src/main/resources/microsite/data/menu.yml +++ /dev/null @@ -1,220 +0,0 @@ -options: - - ############################# - # Type Classes Menu Options # - ############################# - - - title: Type Classes - url: typeclasses.html - menu_type: typeclasses - menu_section: typeclasses - - - title: Semigroups and Monoids - url: typeclasses/semigroup.html - menu_type: typeclasses - menu_section: semigroupsandmonoids - - nested_options: - - title: Semigroup - url: typeclasses/semigroup.html - menu_section: semigroupsandmonoids - - title: Monoid - url: typeclasses/monoid.html - menu_section: semigroupsandmonoids - - - title: Applicative and Traversable Functors - url: typeclasses/applicativetraverse.html - menu_type: typeclasses - menu_section: applicative - - nested_options: - - title: Functor - url: typeclasses/functor.html - menu_section: applicative - - title: Applicative - url: typeclasses/applicative.html - menu_section: applicative - - title: Traverse - url: typeclasses/traverse.html - menu_type: typeclasses - menu_section: applicative - - - title: Monads - url: typeclasses/monad.html - menu_type: typeclasses - menu_section: monads - - - title: Comonads - url: typeclasses/comonad.html - menu_type: typeclasses - menu_section: comonads - - - title: Variance and Functors - url: typeclasses/functor.html - menu_type: typeclasses - menu_section: variance - - nested_options: - - title: Functor - url: typeclasses/functor.html - menu_section: variance - - title: Contravariant - url: typeclasses/contravariant.html - menu_section: variance - - title: ContravariantMonoidal - url: typeclasses/contravariantmonoidal.html - menu_type: typeclasses - - title: Invariant - url: typeclasses/invariant.html - menu_section: variance - - title: InvariantMonoidal - url: typeclasses/invariantmonoidal.html - menu_section: variance - - - title: Alternative - url: typeclasses/alternative.html - menu_type: typeclasses - - - title: Bifunctor - url: typeclasses/bifunctor.html - menu_type: typeclasses - - - title: Eq - url: typeclasses/eq.html - menu_type: typeclasses - - - title: Foldable - url: typeclasses/foldable.html - menu_type: typeclasses - - - title: Parallel - url: typeclasses/parallel.html - menu_type: typeclasses - - - title: SemigroupK - url: typeclasses/semigroupk.html - menu_type: typeclasses - - - title: MonoidK - url: typeclasses/monoidk.html - menu_type: typeclasses - - - title: Show - url: typeclasses/show.html - menu_type: typeclasses - - - title: Reducible - url: typeclasses/reducible.html - menu_type: typeclasses - - - title: ApplicativeError and MonadError - url: typeclasses/applicativemonaderror.html - menu_type: typeclasses - - - title: NonEmptyTraverse - url: typeclasses/nonemptytraverse.html - menu_type: typeclasses - - - title: Arrow - url: typeclasses/arrow.html - menu_type: typeclasses - - - title: Arrow Choice - url: typeclasses/arrowchoice.html - menu_type: typeclasses - - - title: Law Testing - url: typeclasses/lawtesting.html - menu_type: typeclasses - - ########################### - # Data Types Menu Options # - ########################### - - - title: Data Types - url: datatypes.html - menu_type: data - - - title: Chain - url: datatypes/chain.html - menu_type: data - - - title: Const - url: datatypes/const.html - menu_type: data - - - title: ContT - url: datatypes/contt.html - menu_type: data - - - title: Either - url: datatypes/either.html - menu_type: data - - - title: Eval - url: datatypes/eval.html - menu_type: data - - - title: FreeApplicatives - url: datatypes/freeapplicative.html - menu_type: data - - - title: FreeMonads - url: datatypes/freemonad.html - menu_type: data - - - title: FunctionK - url: datatypes/functionk.html - menu_type: data - - - title: Id - url: datatypes/id.html - menu_type: data - - - title: Ior - url: datatypes/ior.html - menu_type: data - - - title: Kleisli - url: datatypes/kleisli.html - menu_type: data - - - title: Writer - url: datatypes/writer.html - menu_type: data - - - title: WriterT - url: datatypes/writert.html - menu_type: data - - - title: Nested - url: datatypes/nested.html - menu_type: data - - - title: NonEmptyList - url: datatypes/nel.html - menu_type: data - - - title: OneAnd - url: datatypes/oneand.html - menu_type: data - - - title: OptionT - url: datatypes/optiont.html - menu_type: data - - - title: EitherT - url: datatypes/eithert.html - menu_type: data - - - title: IorT - url: datatypes/iort.html - menu_type: data - - - title: State - url: datatypes/state.html - menu_type: data - - - title: Validated - url: datatypes/validated.html - menu_type: data diff --git a/docs/src/main/mdoc/typeclasses/typeclasses.md b/docs/typeclasses.md similarity index 82% rename from docs/src/main/mdoc/typeclasses/typeclasses.md rename to docs/typeclasses.md index 47b9ed60d8..e703e03067 100644 --- a/docs/src/main/mdoc/typeclasses/typeclasses.md +++ b/docs/typeclasses.md @@ -1,4 +1,4 @@ -# Type classes +# Type Classes Type classes are a powerful tool used in functional programming to enable ad-hoc polymorphism, more commonly known as overloading. Where many object-oriented languages leverage subtyping for polymorphic code, functional programming tends towards a combination of parametric polymorphism (think type parameters, like Java generics) @@ -225,7 +225,7 @@ val result = Monoid[Int].combine(sumLeft, sumRight) Cats provides laws for type classes via the `kernel-laws` and `laws` modules which makes law checking type class instances easy. -You can find out more about law testing [here](typeclasses/lawtesting.html). +You can find out more about law testing [here](typeclasses/lawtesting.md). ## Type classes in Cats @@ -240,18 +240,18 @@ Originally from [@alexknvl](https://gist.github.com/alexknvl/d63508ddb6a728015ac | Type | Functor | Apply | Applicative | Monad | MonoidK | ApplicativeError | MonadError | CoflatMap | Comonad | Bimonad | | --------------- |:-------:|:-----------------:|:-----------:|:-----:|:-------:|:-----------------:|:----------:|:---------:|:-------:|:-------:| -| Id[A] | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | -| Eval[A] | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | -| Option[A] | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ |✗ | -| Const[K, A] | ✔ | ✔ (`K:Monoid`) | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |✗ | -| Either[E, A] | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ |✗ | -| List[A] | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ |✗ | -| NonEmptyList[A] | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | -| Stream[A] | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ |✗ | -| Map[K, A] | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ |✗ | -| Validated[E, A] | ✔ | ✔ (`E: Semigroup`)| ✔ | ✗ | ✗ | ✔ (`E: Semigroup`)| ✗ | ✗ | ✗ |✗ | -| Reader[E, A] | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ |✗ | -| Writer[E, A] | ✔ | ✔ (`E:Monoid`) | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✗ |✗ | +| `Id[A]` | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | +| `Eval[A]` | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | +| `Option[A]` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ |✗ | +| `Const[K, A]` | ✔ | ✔ (`K:Monoid`) | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |✗ | +| `Either[E, A]` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ |✗ | +| `List[A]` | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ |✗ | +| `NonEmptyList[A]` | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✔ |✔ | +| `Stream[A]` | ✔ | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ |✗ | +| `Map[K, A]` | ✔ | ✔ | ✗ | ✗ | ✔ | ✗ | ✗ | ✗ | ✗ |✗ | +| `Validated[E, A]` | ✔ | ✔ (`E: Semigroup`)| ✔ | ✗ | ✗ | ✔ (`E: Semigroup`)| ✗ | ✗ | ✗ |✗ | +| `Reader[E, A]` | ✔ | ✔ | ✔ | ✔ | ✗ | ✗ | ✗ | ✗ | ✗ |✗ | +| `Writer[E, A]` | ✔ | ✔ (`E:Monoid`) | ✔ | ✔ | ✗ | ✗ | ✗ | ✔ | ✗ |✗ | diff --git a/docs/src/main/mdoc/typeclasses/alternative.md b/docs/typeclasses/alternative.md similarity index 96% rename from docs/src/main/mdoc/typeclasses/alternative.md rename to docs/typeclasses/alternative.md index 3f03ada921..3eaae295cd 100644 --- a/docs/src/main/mdoc/typeclasses/alternative.md +++ b/docs/typeclasses/alternative.md @@ -1,12 +1,5 @@ ---- -layout: docs -title: "Alternative" -section: "typeclasses" -source: "core/src/main/scala/cats/Alternative.scala" -scaladoc: "#cats.Alternative" ---- # Alternative -Alternative extends [`Applicative`](applicative.html) with a [`MonoidK`](monoidk.html). +Alternative extends [`Applicative`](applicative.md) with a [`MonoidK`](monoidk.md). Let's stub out all the operations just to remind ourselves what that gets us. ```scala mdoc:silent diff --git a/docs/src/main/mdoc/typeclasses/applicative.md b/docs/typeclasses/applicative.md similarity index 96% rename from docs/src/main/mdoc/typeclasses/applicative.md rename to docs/typeclasses/applicative.md index 63801c6279..443295a473 100644 --- a/docs/src/main/mdoc/typeclasses/applicative.md +++ b/docs/typeclasses/applicative.md @@ -1,12 +1,5 @@ ---- -layout: docs -title: "Applicative" -section: "typeclasses" -source: "core/src/main/scala/cats/Applicative.scala" -scaladoc: "#cats.Applicative" ---- # Applicative -`Applicative` extends [`Functor`](functor.html) with an `ap` and `pure` method. +`Applicative` extends [`Functor`](functor.md) with an `ap` and `pure` method. ```scala mdoc:silent import cats.Functor @@ -104,7 +97,7 @@ but `map` doesn't give us enough power to do that. Hence, `ap`. ## Applicatives compose -Like [`Functor`](functor.html), `Applicative`s compose. If `F` and `G` have `Applicative` instances, then so +Like [`Functor`](functor.md), `Applicative`s compose. If `F` and `G` have `Applicative` instances, then so does `F[G[_]]`. ```scala mdoc:silent diff --git a/docs/src/main/mdoc/typeclasses/applicativemonaderror.md b/docs/typeclasses/applicativemonaderror.md similarity index 98% rename from docs/src/main/mdoc/typeclasses/applicativemonaderror.md rename to docs/typeclasses/applicativemonaderror.md index df96ca508a..f9df405f11 100644 --- a/docs/src/main/mdoc/typeclasses/applicativemonaderror.md +++ b/docs/typeclasses/applicativemonaderror.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Applicative Error" -section: "typeclasses" -source: "core/src/main/scala/cats/ApplicativeError.scala" -scaladoc: "#cats.ApplicativeError" ---- # ApplicativeError and MonadError ## Applicative Error diff --git a/docs/src/main/mdoc/typeclasses/applicativetraverse.md b/docs/typeclasses/applicativetraverse.md similarity index 94% rename from docs/src/main/mdoc/typeclasses/applicativetraverse.md rename to docs/typeclasses/applicativetraverse.md index ccdda75e3b..5786d7d2d3 100644 --- a/docs/src/main/mdoc/typeclasses/applicativetraverse.md +++ b/docs/typeclasses/applicativetraverse.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Applicative and Traversable Functors" -section: "typeclasses" -scaladoc: "#cats.Functor" ---- - # Applicative and Traversable Functors ## An example from the standard library diff --git a/docs/src/main/mdoc/typeclasses/arrow.md b/docs/typeclasses/arrow.md similarity index 98% rename from docs/src/main/mdoc/typeclasses/arrow.md rename to docs/typeclasses/arrow.md index 5f1b02be86..65b5fa4eb2 100644 --- a/docs/src/main/mdoc/typeclasses/arrow.md +++ b/docs/typeclasses/arrow.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Arrow" -section: "typeclasses" -source: "core/src/main/scala/cats/arrow/Arrow.scala" -scaladoc: "#cats.arrow.Arrow" ---- # Arrow `Arrow` is a type class for modeling composable relationships between two types. One example of such a composable relationship is function `A => B`; other examples include `cats.data.Kleisli`(wrapping an `A => F[B]`, also known as `ReaderT`), and `cats.data.Cokleisli`(wrapping an `F[A] => B`). These type constructors all have `Arrow` instances. An arrow `F[A, B]` can be thought of as representing a computation from `A` to `B` with some context, just like a functor/applicative/monad `F[A]` represents a value `A` with some context. diff --git a/docs/src/main/mdoc/typeclasses/arrowchoice.md b/docs/typeclasses/arrowchoice.md similarity index 90% rename from docs/src/main/mdoc/typeclasses/arrowchoice.md rename to docs/typeclasses/arrowchoice.md index 964104dc26..1c77ed79ad 100644 --- a/docs/src/main/mdoc/typeclasses/arrowchoice.md +++ b/docs/typeclasses/arrowchoice.md @@ -1,13 +1,6 @@ ---- -layout: docs -title: "Arrow Choice" -section: "typeclasses" -source: "core/src/main/scala/cats/arrow/ArrowChoice.scala" -scaladoc: "#cats.arrow.ArrowChoice" ---- +{% laika.title = Arrow Choice %} - -# `Choice` +# Choice Usually we deal with function more often, we're so familiar with `A => B`. @@ -30,7 +23,7 @@ A very useful case of `Choice` is middleware in HTTP server. Take Http4s for example: -HttpRoutes[F] in Http4s is defined as [Kleisli](https://typelevel.org/cats/datatypes/kleisli.html) +`HttpRoutes[F]` in Http4s is defined as [Kleisli](../datatypes/kleisli.md) ```scala type HttpRoutes[F[_]] = Kleisli[OptionT[F, *], Request[F], Response[F]] @@ -74,7 +67,7 @@ Another example will be HTTP response handler. val resp: IO[Either[Throwable, String]] = httpClient.expect[String](uri"https://google.com/").attempt ``` -`attempt` is syntax from [`MonadError`](https://typelevel.org/cats/api/cats/MonadError.html) +`attempt` is syntax from [`MonadError`](applicativemonaderror.md) When we need to handle error, without `Choice` the handler would be something like: ```scala diff --git a/docs/src/main/mdoc/typeclasses/bifunctor.md b/docs/typeclasses/bifunctor.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/bifunctor.md rename to docs/typeclasses/bifunctor.md index 55b80a3ef0..23425ccc7c 100644 --- a/docs/src/main/mdoc/typeclasses/bifunctor.md +++ b/docs/typeclasses/bifunctor.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Bifunctor" -section: "typeclasses" -source: "core/src/main/scala/cats/Bifunctor.scala" -scaladoc: "#cats.Bifunctor" ---- # Bifunctor `Bifunctor` takes two type parameters instead of one, and is a functor in both diff --git a/docs/src/main/mdoc/typeclasses/bimonad.md b/docs/typeclasses/bimonad.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/bimonad.md rename to docs/typeclasses/bimonad.md index 074b71c181..7e0f23dfe7 100644 --- a/docs/src/main/mdoc/typeclasses/bimonad.md +++ b/docs/typeclasses/bimonad.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Bimonad" -section: "typeclasses" -source: "core/src/main/scala/cats/Bimonad.scala" -scaladoc: "#cats.Bimonad" ---- # Bimonad The `Bimonad` trait directly extends `Monad` and `Comonad` without introducing new methods. `Bimonad` is diff --git a/docs/src/main/mdoc/typeclasses/comonad.md b/docs/typeclasses/comonad.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/comonad.md rename to docs/typeclasses/comonad.md index 174808afba..c117c85655 100644 --- a/docs/src/main/mdoc/typeclasses/comonad.md +++ b/docs/typeclasses/comonad.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Comonad" -section: "typeclasses" -source: "core/src/main/scala/cats/Comonad.scala" -scaladoc: "#cats.Comonad" ---- # Comonad `Comonad` is a `Functor` and provides duals of the [`Monad`](monad.html) `pure` diff --git a/docs/src/main/mdoc/typeclasses/contravariant.md b/docs/typeclasses/contravariant.md similarity index 94% rename from docs/src/main/mdoc/typeclasses/contravariant.md rename to docs/typeclasses/contravariant.md index 73678c17ff..c68d54974f 100644 --- a/docs/src/main/mdoc/typeclasses/contravariant.md +++ b/docs/typeclasses/contravariant.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Contravariant" -section: "typeclasses" -source: "core/src/main/scala/cats/Contravariant.scala" -scaladoc: "#cats.Contravariant" ---- # Contravariant The `Contravariant` type class is for functors that define a `contramap` diff --git a/docs/src/main/mdoc/typeclasses/contravariantmonoidal.md b/docs/typeclasses/contravariantmonoidal.md similarity index 94% rename from docs/src/main/mdoc/typeclasses/contravariantmonoidal.md rename to docs/typeclasses/contravariantmonoidal.md index cae9d0ea20..93b4e528c3 100644 --- a/docs/src/main/mdoc/typeclasses/contravariantmonoidal.md +++ b/docs/typeclasses/contravariantmonoidal.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Contravariant Monoidal" -section: "typeclasses" -source: "core/src/main/scala/cats/ContravariantMonoidal.scala" -scaladoc: "#cats.ContravariantMonoidal" ---- # Contravariant Monoidal The `ContravariantMonoidal` type class is for [`Contravariant`](contravariant.html) functors that can define a diff --git a/docs/typeclasses/directory.conf b/docs/typeclasses/directory.conf new file mode 100644 index 0000000000..f413f55d31 --- /dev/null +++ b/docs/typeclasses/directory.conf @@ -0,0 +1 @@ +laika.title = Type Classes diff --git a/docs/src/main/mdoc/typeclasses/eq.md b/docs/typeclasses/eq.md similarity index 93% rename from docs/src/main/mdoc/typeclasses/eq.md rename to docs/typeclasses/eq.md index b97204d4f3..dfb190d7b8 100644 --- a/docs/src/main/mdoc/typeclasses/eq.md +++ b/docs/typeclasses/eq.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "Eq" -section: "typeclasses" -source: "kernel/src/main/scala/cats/kernel/Eq.scala" -scaladoc: "#cats.kernel.Eq" ---- - # Eq Eq is an alternative to the standard Java `equals` method. diff --git a/docs/src/main/mdoc/typeclasses/foldable.md b/docs/typeclasses/foldable.md similarity index 97% rename from docs/src/main/mdoc/typeclasses/foldable.md rename to docs/typeclasses/foldable.md index 87dc2d9b5b..9078541731 100644 --- a/docs/src/main/mdoc/typeclasses/foldable.md +++ b/docs/typeclasses/foldable.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Foldable" -section: "typeclasses" -source: "core/src/main/scala/cats/Foldable.scala" -scaladoc: "#cats.Foldable" ---- # Foldable Foldable type class instances can be defined for data structures that can be diff --git a/docs/src/main/mdoc/typeclasses/functor.md b/docs/typeclasses/functor.md similarity index 96% rename from docs/src/main/mdoc/typeclasses/functor.md rename to docs/typeclasses/functor.md index 3172caf9ac..4b2c0e2445 100644 --- a/docs/src/main/mdoc/typeclasses/functor.md +++ b/docs/typeclasses/functor.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Functor" -section: "typeclasses" -source: "core/src/main/scala/cats/Functor.scala" -scaladoc: "#cats.Functor" ---- # Functor `Functor` is a type class that abstracts over type constructors that can be `map`'ed over. Examples of such type constructors are `List`, `Option`, and `Future`. diff --git a/docs/src/main/mdoc/typeclasses/imports.md b/docs/typeclasses/imports.md similarity index 72% rename from docs/src/main/mdoc/typeclasses/imports.md rename to docs/typeclasses/imports.md index ef13e73078..4c9ada6c84 100644 --- a/docs/src/main/mdoc/typeclasses/imports.md +++ b/docs/typeclasses/imports.md @@ -1,8 +1,3 @@ ---- -layout: docs -title: "Imports" -section: "imports" ---- # Imports The easiest approach to Сats imports is to import everything that's commonly needed: @@ -13,7 +8,7 @@ import cats.data._ import cats.syntax.all._ ``` -The `cats._` import brings in quite a few [type classes](http://typelevel.org/cats/typeclasses.html) (similar to interfaces) such as [Monad](http://typelevel.org/cats/typeclasses/monad.html), [Semigroup](http://typelevel.org/cats/typeclasses/semigroup.html), and [Foldable](http://typelevel.org/cats/typeclasses/foldable.html). Instead of the entire `cats` package, you can import only the types that you need, for example: +The `cats._` import brings in quite a few [type classes](typeclasses.html) (similar to interfaces) such as [Monad](typeclasses/monad.html), [Semigroup](typeclasses/semigroup.html), and [Foldable](typeclasses/foldable.html). Instead of the entire `cats` package, you can import only the types that you need, for example: ```scala mdoc:reset:silent import cats.Monad @@ -21,7 +16,7 @@ import cats.Semigroup import cats.Foldable ``` -The `cats.data._`, import brings in data structures such as [Validated](http://typelevel.org/cats/datatypes/validated.html) and [State](http://typelevel.org/cats/datatypes/state.html). Instead of the entire `cats.data` package, you can import only the types that you need, for example: +The `cats.data._`, import brings in data structures such as [Validated](datatypes/validated.html) and [State](datatypes/state.html). Instead of the entire `cats.data` package, you can import only the types that you need, for example: ```scala mdoc:reset:silent import cats.data.Validated diff --git a/docs/src/main/mdoc/typeclasses/invariant.md b/docs/typeclasses/invariant.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/invariant.md rename to docs/typeclasses/invariant.md index c9f7be4727..cda6e5d3b0 100644 --- a/docs/src/main/mdoc/typeclasses/invariant.md +++ b/docs/typeclasses/invariant.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Invariant" -section: "typeclasses" -source: "core/src/main/scala/cats/Invariant.scala" -scaladoc: "#cats.Invariant" ---- # Invariant The `Invariant` type class is for functors that define an `imap` diff --git a/docs/src/main/mdoc/typeclasses/invariantmonoidal.md b/docs/typeclasses/invariantmonoidal.md similarity index 97% rename from docs/src/main/mdoc/typeclasses/invariantmonoidal.md rename to docs/typeclasses/invariantmonoidal.md index 712dfdbc01..472f45a515 100644 --- a/docs/src/main/mdoc/typeclasses/invariantmonoidal.md +++ b/docs/typeclasses/invariantmonoidal.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "InvariantMonoidal" -section: "typeclasses" -source: "https://github.com/non/cats/blob/main/core/src/main/scala/cats/InvariantMonoidal.scala" -scaladoc: "#cats.InvariantMonoidal" ---- # Invariant Monoidal `InvariantMonoidal` combines [`Invariant`](invariant.html) and `Semigroupal` with the addition of a `unit` methods, defined in isolation the `InvariantMonoidal` type class could be defined as follows: diff --git a/docs/src/main/mdoc/typeclasses/lawtesting.md b/docs/typeclasses/lawtesting.md similarity index 97% rename from docs/src/main/mdoc/typeclasses/lawtesting.md rename to docs/typeclasses/lawtesting.md index e796b7f93e..899cb6da83 100644 --- a/docs/src/main/mdoc/typeclasses/lawtesting.md +++ b/docs/typeclasses/lawtesting.md @@ -1,12 +1,6 @@ ---- -layout: docs -title: "Law Testing" -section: "typeclasses" ---- - # Law testing -[Laws](https://typelevel.org/cats/typeclasses.html#laws) are an important part of cats. +[Laws](typeclasses.html#laws) are an important part of cats. Cats uses [discipline](https://github.com/typelevel/discipline) to define type class laws and the [ScalaCheck](https://github.com/rickynils/scalacheck) tests based on them. diff --git a/docs/src/main/mdoc/typeclasses/monad.md b/docs/typeclasses/monad.md similarity index 97% rename from docs/src/main/mdoc/typeclasses/monad.md rename to docs/typeclasses/monad.md index 505cca2862..b9aec19cbd 100644 --- a/docs/src/main/mdoc/typeclasses/monad.md +++ b/docs/typeclasses/monad.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Monad" -section: "typeclasses" -source: "core/src/main/scala/cats/Monad.scala" -scaladoc: "#cats.Monad" ---- # Monad `Monad` extends the [`Applicative`](applicative.html) type class with a diff --git a/docs/src/main/mdoc/typeclasses/monoid.md b/docs/typeclasses/monoid.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/monoid.md rename to docs/typeclasses/monoid.md index 5b84ec83fc..1cfb556da1 100644 --- a/docs/src/main/mdoc/typeclasses/monoid.md +++ b/docs/typeclasses/monoid.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Monoid" -section: "typeclasses" -source: "kernel/src/main/scala/cats/kernel/Monoid.scala" -scaladoc: "#cats.kernel.Monoid" ---- # Monoid `Monoid` extends the power of `Semigroup` by providing an additional `empty` value. diff --git a/docs/src/main/mdoc/typeclasses/monoidk.md b/docs/typeclasses/monoidk.md similarity index 93% rename from docs/src/main/mdoc/typeclasses/monoidk.md rename to docs/typeclasses/monoidk.md index cc7df1c0d2..092f8a0da2 100644 --- a/docs/src/main/mdoc/typeclasses/monoidk.md +++ b/docs/typeclasses/monoidk.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "MonoidK" -section: "typeclasses" -source: "core/src/main/scala/cats/MonoidK.scala" -scaladoc: "#cats.MonoidK" ---- # MonoidK `MonoidK` is a universal monoid which operates on type constructors of one argument. diff --git a/docs/src/main/mdoc/typeclasses/nonemptytraverse.md b/docs/typeclasses/nonemptytraverse.md similarity index 92% rename from docs/src/main/mdoc/typeclasses/nonemptytraverse.md rename to docs/typeclasses/nonemptytraverse.md index e5421251b4..e7e3e33255 100644 --- a/docs/src/main/mdoc/typeclasses/nonemptytraverse.md +++ b/docs/typeclasses/nonemptytraverse.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "NonEmptyTraverse" -section: "typeclasses" -source: "core/src/main/scala/cats/NonEmptyTraverse.scala" -scaladoc: "#cats.NonEmptyTraverse" ---- - # NonEmptyTraverse `NonEmptyTraverse` is a non-empty version of the [Traverse](traverse.html) type class, just like [Reducible](reducible.html) is a non-empty version of [Foldable](foldable.html). diff --git a/docs/src/main/mdoc/typeclasses/parallel.dot b/docs/typeclasses/parallel.dot similarity index 100% rename from docs/src/main/mdoc/typeclasses/parallel.dot rename to docs/typeclasses/parallel.dot diff --git a/docs/src/main/mdoc/typeclasses/parallel.md b/docs/typeclasses/parallel.md similarity index 96% rename from docs/src/main/mdoc/typeclasses/parallel.md rename to docs/typeclasses/parallel.md index 0d7444d495..80a96c98d8 100644 --- a/docs/src/main/mdoc/typeclasses/parallel.md +++ b/docs/typeclasses/parallel.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Parallel" -section: "typeclasses" -source: "core/src/main/scala/cats/Parallel.scala" -scaladoc: "#cats.Parallel" ---- # Parallel When browsing the various `Monads` included in Cats, diff --git a/docs/src/main/mdoc/typeclasses/reducible.md b/docs/typeclasses/reducible.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/reducible.md rename to docs/typeclasses/reducible.md index 22575318cb..6bcc516e58 100644 --- a/docs/src/main/mdoc/typeclasses/reducible.md +++ b/docs/typeclasses/reducible.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "Reducible" -section: "typeclasses" -source: "core/src/main/scala/cats/Reducible.scala" -scaladoc: "#cats.Reducible" ---- - # Reducible `Reducible` extends the `Foldable` type class with additional `reduce` methods. diff --git a/docs/src/main/mdoc/typeclasses/semigroup.md b/docs/typeclasses/semigroup.md similarity index 96% rename from docs/src/main/mdoc/typeclasses/semigroup.md rename to docs/typeclasses/semigroup.md index a982df2854..f06e8bfb0c 100644 --- a/docs/src/main/mdoc/typeclasses/semigroup.md +++ b/docs/typeclasses/semigroup.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Semigroup" -section: "typeclasses" -source: "kernel/src/main/scala/cats/kernel/Semigroup.scala" -scaladoc: "#cats.kernel.Semigroup" ---- # Semigroup If a type `A` can form a `Semigroup` it has an **associative** binary operation. diff --git a/docs/src/main/mdoc/typeclasses/semigroupk.md b/docs/typeclasses/semigroupk.md similarity index 95% rename from docs/src/main/mdoc/typeclasses/semigroupk.md rename to docs/typeclasses/semigroupk.md index ff5a027c5a..6000a6bfe3 100644 --- a/docs/src/main/mdoc/typeclasses/semigroupk.md +++ b/docs/typeclasses/semigroupk.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "SemigroupK" -section: "typeclasses" -source: "core/src/main/scala/cats/SemigroupK.scala" -scaladoc: "#cats.SemigroupK" ---- # SemigroupK `SemigroupK` has a very similar structure to [`Semigroup`](semigroup.html), the difference diff --git a/docs/src/main/mdoc/typeclasses/show.md b/docs/typeclasses/show.md similarity index 94% rename from docs/src/main/mdoc/typeclasses/show.md rename to docs/typeclasses/show.md index c2b5eecf40..349d7d434c 100644 --- a/docs/src/main/mdoc/typeclasses/show.md +++ b/docs/typeclasses/show.md @@ -1,10 +1,3 @@ ---- -layout: docs -title: "Show" -section: "typeclasses" -source: "core/src/main/scala/cats/Show.scala" -scaladoc: "#cats.Show" ---- # Show Show is an alternative to the Java `toString` method. diff --git a/docs/src/main/mdoc/typeclasses/traverse.md b/docs/typeclasses/traverse.md similarity index 97% rename from docs/src/main/mdoc/typeclasses/traverse.md rename to docs/typeclasses/traverse.md index 0457ed0d23..05d911f6d6 100644 --- a/docs/src/main/mdoc/typeclasses/traverse.md +++ b/docs/typeclasses/traverse.md @@ -1,11 +1,3 @@ ---- -layout: docs -title: "Traverse" -section: "typeclasses" -source: "core/src/main/scala/cats/Traverse.scala" -scaladoc: "#cats.Traverse" ---- - # Traverse In the `Applicative` tutorial we saw a more polymorphic version of the standard library diff --git a/docs/src/main/mdoc/typelevelEcosystem.md b/docs/typelevelEcosystem.md similarity index 98% rename from docs/src/main/mdoc/typelevelEcosystem.md rename to docs/typelevelEcosystem.md index 6ac8f0710a..6c722323a3 100644 --- a/docs/src/main/mdoc/typelevelEcosystem.md +++ b/docs/typelevelEcosystem.md @@ -1,20 +1,3 @@ ---- -layout: page -title: "Typelevel Ecosystem" -section: "" -position: ---- - - -[Cats]: https://typelevel.org/cats/ "Cats" -[Fs2]: https://fs2.io "Fs2" -[Kafka]: https://kafka.apache.org/ "Kafka" -[Monix]: https://monix.io/ "Monix" -[Mules]: https://github.com/davenverse/mules/ "Mules" -[Cats Effect]: https://typelevel.org/cats-effect/ "Cats Effect" -[Circe]: https://circe.github.io/circe/ "Circe" -[Log4Cats]: https://typelevel.org/log4cats/ "Log4Cats" - # Typelevel Ecosystem # By sharing the same set of type classes, instances and data types provided by Cats, projects can speak the same “Cats language”, and integrate with each other with ease. @@ -46,7 +29,7 @@ Here you can find a comprehensive list of libraries and projects related to Type | [circuit](https://davenverse.github.io/circuit/) | Functional Circuit Breaker implementation. | | [ciris](https://cir.is/) | Lightweight, extensible, and validated configuration loading in Scala. | | [console4cats](https://console4cats.profunktor.dev/) | Console I/O for [Cats Effect][Cats Effect]. | -| [cormorant]https://davenverse.github.io/cormorant/) | CSV handling library for FP. | +| [cormorant](https://davenverse.github.io/cormorant/) | CSV handling library for FP. | | [coulomb-cats](https://github.com/erikerlandson/coulomb) | [Cats][Cats] typeclass instances for coulomb Quantity. | | [decline](https://ben.kirw.in/decline/) | A composable command-line parser. | | [doobie-pool](https://christopherdavenport.github.io/doobie-pool/) | Doobie Pooling Mechanism in Pure FP. | @@ -100,7 +83,7 @@ Here you can find a comprehensive list of libraries and projects related to Type | [hammock](https://hammock.pepegar.com/) | Purely functional HTTP client. | | [henkan](https://github.com/kailuowang/henkan) | Type safe conversion between case class instances with similar fields. | | [http4s](https://http4s.org/) | Minimal, idiomatic Scala interface for HTTP services using [Fs2][Fs2]. | -| [iota](https://github.com/frees-io/iota) | Fast [co]product types with a clean syntax. | +| [iota](https://github.com/frees-io/iota) | Fast (co)product types with a clean syntax. | | [itto-csv](https://github.com/gekomad/itto-csv) | Pure functional library for working with CSV. | | [jms4s](https://fpinbo.dev/jms4s) | A functional wrapper for jms | | [kafka4s](https://banno.github.io/kafka4s/) | Functional programming with [Kafka][Kafka] and Scala. | @@ -180,16 +163,26 @@ Here you can find a comprehensive list of libraries and projects related to Type Your project talks Cats too? [Submit a PR to add it here!](https://github.com/typelevel/cats/edit/main/docs/src/main/mdoc/typelevelEcosystem.md) -*The full-size [Cats logo](https://typelevel.org/cats/img/cats-logo.png) is available for use for Cats related projects, contents, souvenirs, etc.* +*The full-size [Cats logo](img/cats-logo.png) is available for use for Cats related projects, contents, souvenirs, etc.* -*We offer a [Cats Friendly Badge](https://typelevel.org/cats/img/cats-badge.svg) to let others know your project works with Cats!* +*We offer a [Cats Friendly Badge](img/cats-badge.svg) to let others know your project works with Cats!* -![Cats Friendly Badge](https://typelevel.org/cats/img/cats-badge-normal.png) +![Cats Friendly Badge](img/cats-badge-normal.png) Below are quick html and markdown snippets to use the badge in your own project. ```html -Cats friendly +Cats friendly ``` ```markdown -![Cats Friendly Badge](https://typelevel.org/cats/img/cats-badge-tiny.png) +![Cats Friendly Badge](img/cats-badge-tiny.png) ``` + +[Cats]: "Cats" +[Fs2]: https://fs2.io "Fs2" +[Kafka]: https://kafka.apache.org/ "Kafka" +[Monix]: https://monix.io/ "Monix" +[Mules]: https://github.com/davenverse/mules/ "Mules" +[Cats Effect]: https://typelevel.org/cats-effect/ "Cats Effect" +[Circe]: https://circe.github.io/circe/ "Circe" +[Log4Cats]: https://typelevel.org/log4cats/ "Log4Cats" +