Misc doc changes (#353)

Besides other documentation changes, this commit ensures the generated
HTML doc for HexDocs.pm will become the main source doc for this Elixir
library which leverage on latest features of ExDoc.

Co-authored-by: Sonny Scroggin <sonny@scrogg.in>

Co-authored-by: Sonny Scroggin <sonny@scrogg.in>

Author: kianmeng

rustler_mix/.formatter.exs

@@ -1,3 +1,4 @@
+# Used by "mix format"
 [
   inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]

rustler_mix/.gitignore

@@ -1,5 +1,27 @@
-/_build
-/cover
-/deps
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
-*.ez
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+rustler-*.tar
+
+
+# Temporary files for e.g. tests
+/tmp

rustler_mix/README.md

@@ -1,34 +1,51 @@
 # Rustler
 
-This is the Mix package for [rustler](https://github.com/rusterlium/rustler), a library to write Erlang NIFs in
-safe Rust code. Here, we provide the basic functionality to use Rustler from Elixir:
+[![Module Version](https://img.shields.io/hexpm/v/rustler.svg)](https://hex.pm/packages/rustler)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/rustler/)
+[![Total Download](https://img.shields.io/hexpm/dt/rustler.svg)](https://hex.pm/packages/rustler)
+[![License](https://img.shields.io/hexpm/l/rustler.svg)](https://github.com/rusterlium/rustler/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/rusterlium/rustler.svg)](https://github.com/rusterlium/rustler/commits/master)
 
-- A task to generate a new crate to write NIFs (`mix help rustler.new`)
-
-See below for information on how to install this, which options are exposed through the configuration, and how t
-load a NIF.
+The Mix package for [rustler](https://github.com/rusterlium/rustler), a library to write Erlang Native Implemented Functions (NIFs) in [Rust](https://www.rust-lang.org/) programming language.
 
 ## Installation
 
-This package is available on [`hex.pm`](https://hex.pm/packages/rustler). To install it, add it to your dependencies:
+This package is available on [Hex.pm](https://hex.pm/packages/rustler). To install it, add `:rustler` to your dependencies:
 
 ```elixir
 def deps do
-  [{:rustler, "~> 0.22.0-rc.0"}]
+  [
+    {:rustler, "~> 0.22.0-rc.0"}
+  ]
 end
 ```
 
-Then,
+## Usage
+
+1.  Fetch all necessary dependencies:
+
+    ```
+    $ mix deps.get
+    ```
+2.  Check your installation by showing help from the installed Mix task:
+
+    ```
+    $ mix help rustler.new
+    ```
+
+3.  Generate the boilerplate for a new Rustler project. Follow the instructions
+    to configure your project:
+
+    ```
+    $ mix rustler.new
+    ```
 
-1. Run `mix deps.get` to fetch the dependency.
-1. Run `mix rustler.new` and follow the instructions to generate the boilerplate for your NIF.
-1. Load the NIF in your program. [See below](#loading-the-nif).
+4.  [Load the NIF in your program.](#loading-the-nif).
 
 ## Crate configuration
 
 The Rust crate compilation can be controlled via Mix compile-time configuration in `config/config.exs`.
-See [configuration options](https://hexdocs.pm/rustler/Rustler.html#module-configuration-options) for more
-details.
+See [configuration options](https://hexdocs.pm/rustler/Rustler.html#module-configuration-options) for more details.
 
 
 ## Loading the NIF
@@ -55,3 +72,16 @@ Note that `:crate` is the name in the `[lib]` section of your `Cargo.toml`. The
 `:crate` option is optional if your crate and `otp_app` use the same name.
 
 See the `Rustler` module for more information.
+
+## Copyright and License
+
+Licensed under either of
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

rustler_mix/lib/mix/tasks/rustler.new.ex

@@ -2,7 +2,7 @@ defmodule Mix.Tasks.Rustler.New do
   use Mix.Task
   import Mix.Generator
 
-  @shortdoc "Creates a new Rustler project"
+  @shortdoc "Creates a new Rustler project."
   @moduledoc """
   Generates boilerplate for a new Rustler project.
 

rustler_mix/lib/rustler.ex

@@ -4,7 +4,9 @@ defmodule Rustler do
 
   When used, Rustler expects the `:otp_app` as option.
   The `:otp_app` should point to the OTP application that
-  the dynamic library can be loaded from. For example:
+  the dynamic library can be loaded from.
+
+  For example:
 
       defmodule MyNIF do
         use Rustler, otp_app: :my_nif
@@ -98,7 +100,7 @@ defmodule Rustler do
       @doc false
       def rustler_init do
         # Remove any old modules that may be loaded so we don't get
-        # :error, {:upgrade, 'Upgrade not supported by this NIF library.'}}
+        # {:error, {:upgrade, 'Upgrade not supported by this NIF library.'}}
         :code.purge(__MODULE__)
 
         {otp_app, path} = @load_from

rustler_mix/mix.exs

@@ -1,53 +1,60 @@
 defmodule Rustler.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/rusterlium/rustler"
+  @version "0.22.0-rc.0"
+
   def project do
     [
       app: :rustler,
-      version: rustler_version(),
+      name: "Rustler",
+      version: @version,
       elixir: "~> 1.6",
       build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
-      name: "Rustler",
-      source_url: "https://github.com/rustlerium/rustler",
-      homepage_url: "https://github.com/rusterlium/rustler",
       deps: deps(),
-      docs: [
-        main: "readme",
-        extras: ["README.md", "../CHANGELOG.md"],
-        source_url_pattern:
-          "https://github.com/rusterlium/rustler/blob/rustler-#{rustler_version()}/rustler_mix/%{path}#L%{line}"
-      ],
       package: package(),
-      description: description()
+      docs: docs()
     ]
   end
 
-  def rustler_version, do: "0.22.0-rc.0"
-
   def application do
     [extra_applications: [:logger, :eex]]
   end
 
   defp deps do
     [
       {:toml, "~> 0.5.2", runtime: false},
-      {:ex_doc, "~> 0.21", only: :dev}
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}
     ]
   end
 
-  defp description do
-    """
-    Mix compiler and runtime helpers for Rustler.
-    """
-  end
-
   defp package do
     [
+      description: "Mix compiler and runtime helpers for Rustler.",
       files: ["lib", "priv", "mix.exs", "README.md"],
       maintainers: ["hansihe"],
       licenses: ["MIT", "Apache-2.0"],
-      links: %{"GitHub" => "https://github.com/rusterlium/rustler"}
+      links: %{
+        "Changelog" => "https://hexdocs.pm/rustler/changelog.html",
+        "GitHub" => @source_url
+      }
+    ]
+  end
+
+  defp docs do
+    [
+      extras: [
+        "../CHANGELOG.md",
+        {:"../LICENSE-APACHE", [title: "License (Apache-2.0)"]},
+        {:"../LICENSE-MIT", [title: "License (MIT)"]},
+        "README.md"
+      ],
+      main: "readme",
+      homepage_url: @source_url,
+      source_url: @source_url,
+      source_url_pattern: "#{@source_url}/blob/rustler-#{@version}/rustler_mix/%{path}#L%{line}",
+      formatters: ["html"]
     ]
   end
 end

rustler_mix/mix.lock

@@ -1,8 +1,10 @@
 %{
   "earmark": {:hex, :earmark, "1.4.4", "4821b8d05cda507189d51f2caeef370cf1e18ca5d7dfb7d31e9cafe6688106a4", [:mix], [], "hexpm", "1f93aba7340574847c0f609da787f0d79efcab51b044bb6e242cae5aca9d264d"},
-  "ex_doc": {:hex, :ex_doc, "0.21.3", "857ec876b35a587c5d9148a2512e952e24c24345552259464b98bfbb883c7b42", [:mix], [{:earmark, "~> 1.4", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "0db1ee8d1547ab4877c5b5dffc6604ef9454e189928d5ba8967d4a58a801f161"},
-  "makeup": {:hex, :makeup, "1.0.1", "82f332e461dc6c79dbd82fbe2a9c10d48ed07146f0a478286e590c83c52010b5", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "49736fe5b66a08d8575bf5321d716bac5da20c8e6b97714fec2bcd6febcfa1f8"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.14.0", "cf8b7c66ad1cff4c14679698d532f0b5d45a3968ffbcbfd590339cb57742f1ae", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "d4b316c7222a85bbaa2fd7c6e90e37e953257ad196dc229505137c5e505e9eff"},
-  "nimble_parsec": {:hex, :nimble_parsec, "0.5.3", "def21c10a9ed70ce22754fdeea0810dafd53c2db3219a0cd54cf5526377af1c6", [:mix], [], "hexpm", "589b5af56f4afca65217a1f3eb3fee7e79b09c40c742fddc1c312b3ac0b3399f"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"},
+  "ex_doc": {:hex, :ex_doc, "0.24.2", "e4c26603830c1a2286dae45f4412a4d1980e1e89dc779fcd0181ed1d5a05c8d9", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "e134e1d9e821b8d9e4244687fb2ace58d479b67b282de5158333b0d57c6fb7da"},
+  "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.15.1", "b5888c880d17d1cc3e598f05cdb5b5a91b7b17ac4eaf5f297cb697663a1094dd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "db68c173234b07ab2a07f645a5acdc117b9f99d69ebf521821d89690ae6c6ec8"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
   "toml": {:hex, :toml, "0.5.2", "e471388a8726d1ce51a6b32f864b8228a1eb8edc907a0edf2bb50eab9321b526", [:mix], [], "hexpm", "f1e3dabef71fb510d015fad18c0e05e7c57281001141504c6b69d94e99750a07"},
 }