Skip to content

Commit

Permalink
Consolidate readme.md and index.md (#1915)
Browse files Browse the repository at this point in the history
* consolidate readme and index

* conslidate readme and index, minor polish to docs

* Update faq.md

* Added refined and Monocle to cats ecosystem / reorder

* fix link

* Update README.md

* added cats logo/fixed links

* added scanamo

* Update README.md

* Update README.md
  • Loading branch information
kailuowang authored Sep 20, 2017
1 parent 15a5240 commit 464be03
Show file tree
Hide file tree
Showing 17 changed files with 103 additions and 198 deletions.
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,5 @@ TAGS
*.sublime-workspace
tests.iml
# Auto-copied by sbt-microsites
docs/src/main/tut/contributing.md
docs/src/main/tut/contributing.md
docs/src/main/tut/index.md
90 changes: 36 additions & 54 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
## Cats
![cats image](http://plastic-idolatry.com/erik/cats2.png)

[![Build Status](https://api.travis-ci.org/typelevel/cats.svg)](https://travis-ci.org/typelevel/cats)
[![Workflow](https://badge.waffle.io/typelevel/cats.svg?label=ready&title=Ready)](https://waffle.io/typelevel/cats)
Expand All @@ -9,18 +10,14 @@

### Overview

Cats is a library which provides abstractions for functional programming in Scala.

Cats is a library which provides abstractions for functional programming in the [Scala programming language](https://scala-lang.org).
The name is a playful shortening of the word *category*.

![cats image](http://plastic-idolatry.com/erik/cats2.png)
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.

#### Why?
For more detail about Cats' motivations, go [here](http://typelevel.org/cats/motivations).

Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the
standard library. Cats augments the standard library with tools that further enable functional programming such as
`Validated`, `Monad`, and `Traverse`. A broader goal of Cats is to provide a foundation for an
[ecosystem of pure, typeful libraries](https://github.com/typelevel/cats#the-cats-ecosystem).

### Getting Started

Expand Down Expand Up @@ -51,77 +48,62 @@ functionality, you can pick-and-choose from amongst these modules
* [`cats-mtl`](https://github.com/typelevel/cats-mtl): transformer typeclasses for cats' Monads, Applicatives and Functors.
* [`alleycats`](https://github.com/non/alleycats): cats instances and classes which are not lawful.
* [`mouse`](https://github.com/benhutchison/mouse): a small companion to cats that provides convenient syntax (aka extension methods)


Release notes for Cats are available in [CHANGES.md](CHANGES.md).

*Cats is still under active development. While we don't anticipate any
major redesigns, changes that are neither source nor binary
compatible are to be expected in upcoming cats releases. We will
update the minor version of cats accordingly for such changes. Once
cats 1.0 is released (ETA: Q4 2017), there will be an increased focus
on making changes in compatible ways.*

#### Enhancing type inference

To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification).

### Documentation

Cats information and documentation is available on the
[website](http://typelevel.org/cats).
To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this [sbt plugin](https://github.com/fiadliel/sbt-partial-unification#sbt-partial-unification).

We also have a Scaladoc [index](http://typelevel.org/cats/api/#package).
Release notes for Cats are available in [CHANGES.md](https://github.com/typelevel/cats/blob/master/CHANGES.md).

Finally, we have a list of
[frequently-asked questions](docs/src/main/tut/faq.md).
*Cats is still under active development. While we don't anticipate any
major redesigns, changes that are neither source nor binary
compatible are to be expected in upcoming RC1 and 1.0 releases.*

Our goal is to have clear and comprehensive documentation. If you
notice problems, omissions, or errors, please
[let us know](CONTRIBUTING.md).

### The cats ecosystem
### <a name="ecosystem" href="#ecosystem"></a>The cats ecosystem

Many projects integrate with cats. By sharing the same set of
type classes, instances and data types, projects can speak the same "cats
language", and integrate with each other with ease.
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.

#### General purpose libraries to support pure functional programming

* [Dogs](https://github.com/stew/dogs): pure functional collections and data structures.
* [Dogs](https://github.com/stew/dogs): pure functional collections and data structures
* [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers)
* [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs
* [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax
* [Kittens](https://github.com/milessabin/kittens): automatic type class derivation for Cats and generic utility functions
* [eff](https://github.com/atnos-org/eff): functional effects and effect handlers (alternative to monad transformers).
* [Freestyle](https://github.com/47deg/freestyle): pure functional framework for Free and Tagless Final apps & libs.
* [mainecoon](https://github.com/kailuowang/mainecoon): Transform and compose tagless final encoded algebras
* [iota](https://github.com/frees-io/iota): Fast [co]product types with a clean syntax
* [Monocle](https://github.com/julien-truffaut/Monocle): an optics library for Scala (and Scala.js) strongly inspired by Haskell Lens.
* [newts](https://github.com/julien-truffaut/newts): Defines newtypes compatible with cats type classes
* [origami](https://github.com/atnos-org/origami): monadic folds
* [newts](https://github.com/julien-truffaut/newts): Defines newtypes compatible with cats type classes.
* [refined](https://github.com/fthomas/refined): simple refinement types for Scala

#### Libraries with more specific uses

* [Circe](https://github.com/circe/circe): pure functional JSON library.
* [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources.
* [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark.
* [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library
* [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala
* [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs.
* [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP
* [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client
* [atto](https://github.com/tpolecat/atto): friendly little text parsers
* [circe](https://github.com/circe/circe): pure functional JSON library
* [decline](https://github.com/bkirwi/decline): A composable command-line parser
* [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata
* [doobie](https://github.com/tpolecat/doobie): a pure functional JDBC layer for Scala
* [Fetch](https://github.com/47deg/fetch): efficient data access to heterogeneous data sources
* [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services
* [Frameless](https://github.com/typelevel/frameless): Expressive types for Spark
* [FS2](https://github.com/functional-streams-for-scala): compositional, streaming I/O library
* [grafter](https://github.com/zalando/grafter): dependency-injection library using the `Reader` pattern
* [finch](https://github.com/finagle/finch): Scala combinator library for building Finagle HTTP services
* [hammock](https://github.com/pepegar/hammock): Purely functional HTTP client
* [http4s](https://github.com/http4s/http4s): A minimal, idiomatic Scala interface for HTTP
* [monadic-html](https://github.com/OlivierBlanvillain/monadic-html): Tiny DOM binding library for Scala.js
* [Monix](https://github.com/monix/monix): high-performance library for composing asynchronous and event-based programs
* [pureconfig](https://github.com/pureconfig/pureconfig): A boilerplate-free library for loading configuration files


* [scanamo](https://github.com/guardian/scanamo): simpler DynamoDB access for Scala
* [seals](https://github.com/durban/seals): tools for schema evolution and language-integrated schemata

*Feel free to submit a PR if you want a project you maintain to be added to this list.*

*The full-size [cats logo](https://typelevel.org/cats/img/cats-logo.png) is available for use for Cats related projects, contents, souvenirs, etc.*

### How can I contribute to Cats?

We welcome contributions to Cats and would love for you to help build
Cats. See our [contributor guide](CONTRIBUTING.md) for more
Cats. See our [contributor guide](https://typelevel.org/cats/contributing.html) for more
information about how you can get involved.

### Community
Expand Down Expand Up @@ -216,4 +198,4 @@ http://opensource.org/licenses/mit-license.php and also in the
[COPYING](COPYING) file. The design is informed by many other
projects, in particular [Scalaz](https://github.com/scalaz/scalaz).

Copyright the maintainers, 2015-2016.
Copyright the maintainers, 2015-2017.
7 changes: 6 additions & 1 deletion build.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,12 @@ lazy val docSettings = Seq(
file("CONTRIBUTING.md") -> ExtraMdFileConfig(
"contributing.md",
"home",
Map("title" -> "Contributing", "section" -> "contributing", "position" -> "5")
Map("title" -> "Contributing", "section" -> "contributing", "position" -> "50")
),
file("README.md") -> ExtraMdFileConfig(
"index.md",
"home",
Map("title" -> "Home", "section" -> "home", "position" -> "0")
)
),
micrositeGithubRepo := "cats",
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/src/main/resources/microsite/img/favicon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/src/main/resources/microsite/img/navbar_brand.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/src/main/resources/microsite/img/navbar_brand2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/src/main/resources/microsite/img/sidebar_brand.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/src/main/resources/microsite/img/sidebar_brand2x.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/src/main/tut/colophon.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: page
title: "Colophon"
section: "colophon"
position: 6
position: 60
---
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
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/tut/datatypes.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: docs
title: "Data Types"
section: "data"
position: 2
position: 20
---
# Data Types

Expand Down
9 changes: 4 additions & 5 deletions docs/src/main/tut/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
layout: page
title: "FAQ"
section: "faq"
position: 4
position: 40
---

# Frequently Asked Questions

## Questions
* [What imports do I need?](#what-imports)
* [What is the difference between cats and scalaz](#diff-scalaz)
* [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)
Expand Down Expand Up @@ -38,10 +38,9 @@ This should be all that you need, but if you'd like to learn more about the deta

## <a id="diff-scalaz" href="#diff-scalaz"></a>What is the difference between Cats and Scalaz?

Cats and [Scalaz](https://github.com/scalaz/scalaz) have the same goal: facilitate pure functional programming in Scala applications; 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 libaries 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.
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 took a [modular](/cats/#modularity) approach and focuses on providing core, [binary compatible](/cats/#a-namebinary-compatibility-and-versioning), [approachable](/cats/#approachability) and [efficient](/cats/#efficiency) abstractions. It provides a welcoming and supportive environment for the [user community](https://gitter.im/typelevel/cats) governed
by the [typelevel code of conduct](https://typelevel.org/conduct). It also takes great effort in supplying a comprehensive and beginner-friendly [documentation](/cats/#documentation).
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://gitter.im/typelevel/cats) governed by the [typelevel code of conduct](https://typelevel.org/conduct). It also takes great effort in supplying a comprehensive and beginner-friendly [documentation](/cats/#documentation).


## <a id="either" href="#either"></a>Where is right-biased Either?
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/tut/guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: page
title: "Guidelines"
section: "guidelines"
position: 7
position: 70
---

# Guidelines
Expand Down
Loading

0 comments on commit 464be03

Please sign in to comment.