Improve docs and code regarding ansi formatting

Author: José Valim

lib/ex_unit/mix.exs

@@ -11,6 +11,11 @@ defmodule ExUnit.Mixfile do
     [registered: [ExUnit.Server],
      mod: {ExUnit, []},
      env: [
+       # Calculated on demand
+       # max_cases: :erlang.system_info(:schedulers_online),
+       # color: IO.ANSI.terminal?,
+       # seed: rand(),
+
        autorun: true,
        trace: false,
        formatters: [ExUnit.CLIFormatter],

lib/iex/lib/iex.ex

@@ -445,7 +445,10 @@ defmodule IEx do
 
   @doc false
   def default_colors do
-    [# Used by default on evaluation cycle
+    [# Enabled should be commented as it is calculated if missing
+     # enabled: true,
+
+     # Used by default on evaluation cycle
      eval_interrupt: "yellow",
      eval_result:    "yellow",
      eval_error:     "red",

lib/iex/lib/iex/introspection.ex

@@ -15,10 +15,9 @@ defmodule IEx.Introspection do
         if function_exported?(module, :__info__, 1) do
           case module.__info__(:moduledoc) do
             {_, binary} when is_binary(binary) ->
-              if IO.ANSI.terminal? do
-                options = docs_options()
-                IO.ANSI.Docs.print_heading(inspect(module), options)
-                IO.ANSI.Docs.print(binary, options)
+              if opts = ansi_docs() do
+                IO.ANSI.Docs.print_heading(inspect(module), opts)
+                IO.ANSI.Docs.print(binary, opts)
               else
                 IO.puts "* #{inspect(module)}\n"
                 IO.puts binary
@@ -159,10 +158,9 @@ defmodule IEx.Introspection do
     heading = "#{kind} #{fun}(#{args})"
     doc     = doc || ""
 
-    if IO.ANSI.terminal? do
-      options = docs_options()
-      IO.ANSI.Docs.print_heading(heading, options)
-      IO.ANSI.Docs.print(doc, options)
+    if opts = ansi_docs() do
+      IO.ANSI.Docs.print_heading(heading, opts)
+      IO.ANSI.Docs.print(doc, opts)
     else
       IO.puts "* #{heading}\n"
       IO.puts doc
@@ -177,8 +175,11 @@ defmodule IEx.Introspection do
     atom_to_binary(var)
   end
 
-  defp docs_options() do
-    [width: IEx.width] ++ Application.get_env(:iex, :colors)
+  defp ansi_docs() do
+    opts = Application.get_env(:iex, :colors)
+    if opts[:enabled] do
+      [width: IEx.width] ++ opts
+    end
   end
 
   @doc """

lib/iex/test/iex/interaction_test.exs

@@ -113,7 +113,7 @@ defmodule IEx.InteractionTest do
       # Test that ANSI escapes in the docs are left alone
       opts = [colors: [enabled: true]]
       assert capture_iex("h IEx.InteractionTest.ansi_escapes", opts)
-             == "* def ansi_escapes()\n\nHello, I have %{red}ANSI%{reset} escapes."
+             =~ ~r"Hello, I have %\{red}ANSI%\{reset} escapes"
 
       # Test that ANSI escapes in iex output are left alone
       opts = [colors: [enabled: true, eval_result: "red", eval_info: "red"]]

lib/mix/lib/mix/tasks/help.ex

@@ -4,15 +4,34 @@ defmodule Mix.Tasks.Help do
   @shortdoc "Print help information for tasks"
 
   @moduledoc """
-  If given a task name, prints the documentation for that task.
-  If no task name is given, prints the short form documentation
-  for all tasks.
+  Lists all tasks or prints the documentation for a given task.
 
   ## Arguments
 
       mix help      - prints all tasks and their shortdoc
       mix help TASK - prints full docs for the given task
 
+  ## Colors
+
+  When possible, `mix help` is going to use coloring for formatting
+  guides. The formatting can be customized by configuring the Mix
+  application either inside your project (in `config/config.exs`) or
+  by using the local config (in `~/.mix/config.exs`).
+
+  For example, to disable, one may:
+
+      [mix: [colors: [enabled: false]]]
+
+  The available color options are:
+
+  * `:enabled`         - show ANSI formatting (defaults to IO.ANSI.terminal?)
+  * `:doc_code`        — the attributes for code blocks (cyan, bright)
+  * `:doc_inline_code` - inline code (cyan)
+  * `:doc_headings`    - h1 and h2 (yellow, bright)
+  * `:doc_title`       — the overall heading for the output (reverse,yellow,bright)
+  * `:doc_bold`        - (bright)
+  * `:doc_underline`   - (underline)
+
   """
 
   def run([]) do
@@ -42,11 +61,12 @@ defmodule Mix.Tasks.Help do
   def run([task]) do
     module = Mix.Task.get!(task)
     doc    = Mix.Task.moduledoc(module) || "There is no documentation for this task"
+    opts   = Application.get_env(:mix, :colors)
 
-    if IO.ANSI.terminal? do
-      options = [width: width] ++ Application.get_env(:mix, :colors)
-      IO.ANSI.Docs.print_heading("mix help #{task}", options)
-      IO.ANSI.Docs.print(doc, options)
+    if ansi_docs?(opts) do
+      opts = [width: width] ++ opts
+      IO.ANSI.Docs.print_heading("mix help #{task}", opts)
+      IO.ANSI.Docs.print(doc, opts)
     else
       IO.puts "# mix help #{task}\n"
       IO.puts doc
@@ -59,6 +79,14 @@ defmodule Mix.Tasks.Help do
     raise Mix.Error, message: "Unexpected arguments, expected `mix help` or `mix help TASK`"
   end
 
+  defp ansi_docs?(opts) do
+    if Keyword.has_key?(opts, :enabled) do
+      opts[:enabled]
+    else
+      IO.ANSI.terminal?
+    end
+  end
+
   defp width() do
     case :io.columns(:standard_input) do
       {:ok, width} -> min(width, 80)