From 636c98680591db7cbf1c3c278515eec4001b1d79 Mon Sep 17 00:00:00 2001
From: Jon Parise <jon@pinterest.com>
Date: Wed, 1 Aug 2018 11:26:26 -0700
Subject: [PATCH] Use the Thrift module as the main docs page (#374)

This adds some initial high-level documentation to the `Thrift` module.
There are still many details that only exist in README.md, but this is
enough for us to remove that file from the generated documentation.

This change also adds a section grouping for the Thrift.AST modules.
---
 CONTRIBUTING.md |  2 +-
 lib/thrift.ex   | 54 ++++++++++++++++++++++++++++++++++++++++++++-----
 mix.exs         |  9 ++++++---
 3 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2dc5368..2bb2195 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ maintainers will merge your contribution.
 
 To increase the chances that your pull request will be accepted:
 
-- Follow our [style guide](#Style)
+- Follow our [style guide](#style)
 - Write tests for your changes
 - Write a good commit message
 
diff --git a/lib/thrift.ex b/lib/thrift.ex
index 3e13ac3..ae23a35 100644
--- a/lib/thrift.ex
+++ b/lib/thrift.ex
@@ -1,12 +1,56 @@
 defmodule Thrift do
   @moduledoc ~S"""
-  Thrift provides [Apache Thrift](http://thrift.apache.org/) support:
+  [Thrift](https://thrift.apache.org/) implementation for Elixir including a
+  Thrift IDL parser, a code generator, and an RPC system
 
-  * `Mix.Tasks.Compile.Thrift` - mix task for generate Erlang source files
-  from `.thrift` schema files
+  ## Thrift IDL Parsing
 
-  * `Thrift.Parser` - functions for parsing `.thift` schema files into a
-  `Thrift.AST` tree
+  `Thrift.Parser` parses [Thrift IDL](https://thrift.apache.org/docs/idl) into
+  an abstract syntax tree used for code generation. You can also work with
+  `Thrift.AST` directly to support additional use cases, such as building
+  linters or analysis tools.
+
+  ## Code Generation
+
+  `Mix.Tasks.Compile.Thrift` is a Mix compiler task that automates Thrift code
+  generation. To use it, add `:thrift` to your project's `:compilers` list.
+  For example:
+
+      compilers: [:thrift | Mix.compilers]
+
+  It's important to add `:thrift` *before* the `:elixir` compiler entry. The
+  Thrift compiler generates Elixir source files, which are in turn compiled by
+  the `:elixir` compiler.
+
+  Configure the compiler using a keyword list under the top-level `:thrift`
+  key. The only required compiler option is `:files`, which defines the list
+  of Thrift files to compile. See `Mix.Tasks.Compile.Thrift` for the full set
+  of available options.
+
+  By default, the generated Elixir source files will be written to the `lib`
+  directory, but you can change that using the `output_path` option.
+
+  In this example, we gather all of the `.thrift` files under the `thrift`
+  directory and write our output files to the `lib/generated` directory:
+
+      defmodule MyProject.Mixfile do
+        # ...
+        def project do
+          [
+            # ...
+            compilers: [:thrift | Mix.compilers],
+            thrift: [
+              files: Path.wildcard("thrift/**/*.thrift"),
+              output_path: "lib/generated"
+            ]
+          ]
+        end
+      end
+
+  You can also use the `Mix.Tasks.Thrift.Generate` Mix task to generate code
+  on-demand. By default, it uses the same project configuration as the
+  compiler task above, but options can also be specified using command line
+  arguments.
   """
 
   @typedoc "Thrift data types"
diff --git a/mix.exs b/mix.exs
index 58bcfd5..02ed911 100644
--- a/mix.exs
+++ b/mix.exs
@@ -50,9 +50,12 @@ defmodule Thrift.Mixfile do
       # Docs
       name: "Thrift",
       docs: [
-        main: "README",
-        extras: ["README.md": [title: "README"], "CONTRIBUTING.md": [title: "Contributing"]],
-        source_url: @project_url
+        main: "Thrift",
+        extras: ["CONTRIBUTING.md": [title: "Contributing"]],
+        source_url: @project_url,
+        groups_for_modules: [
+          "Abstract Syntax Tree": ~r"Thrift.AST.*"
+        ]
       ]
     ]
   end