Consolidate readme.md and index.md (#1915)

* 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

.gitignore

@@ -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

README.md

@@ -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)
@@ -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
 
@@ -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
@@ -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.

build.sbt

@@ -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",

docs/src/main/tut/colophon.md

@@ -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

docs/src/main/tut/datatypes.md

@@ -2,7 +2,7 @@
 layout: docs
 title:  "Data Types"
 section: "data"
-position: 2
+position: 20
 ---
 # Data Types
 

docs/src/main/tut/faq.md

@@ -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)
@@ -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?

docs/src/main/tut/guidelines.md

@@ -2,7 +2,7 @@
 layout: page
 title:  "Guidelines"
 section: "guidelines"
-position: 7
+position: 70
 ---
 
 # Guidelines