Add contribution instructions

README.md

@@ -108,7 +108,16 @@ Update your project configuration to use Cmark:
 docs: [markdown_processor: ExDoc.Markdown.Cmark]
 ```
 
-# License
+## Contributing
+
+The easiest way to test changes to ExDoc is to locally re-generate it's own docs:
+
+1. Run `mix setup` to install all dependencies
+2. Run `mix docs` to generate docs. Note, ExDoc defines `docs` alias for local development,
+   see [`mix.exs`](./mix.exs) for more details
+3. Commit both `assets/*` and (after running `mix docs`) `formatters/*` changes
+
+## License
 
 ExDoc source code is released under Apache 2 License. The generated contents, however, are under different licenses based on projects used to help render HTML, including CSS, JS, and other assets.
 

mix.exs

@@ -35,7 +35,9 @@ defmodule ExDoc.Mixfile do
 
   defp aliases do
     [
-      clean: [&clean_test_fixtures/1, "clean"]
+      clean: [&clean_test_fixtures/1, "clean"],
+      setup: ["deps.get", &setup_assets/1],
+      docs: [&maybe_build_assets/1, "compile --force", "docs"]
     ]
   end
 
@@ -85,6 +87,25 @@ defmodule ExDoc.Mixfile do
   end
 
   defp clean_test_fixtures(_args) do
-    File.rm_rf "test/tmp"
+    File.rm_rf("test/tmp")
+  end
+
+  defp setup_assets(_args) do
+    cmd("yarn", ~w(install))
+  end
+
+  defp maybe_build_assets(_args) do
+    if Mix.env() == :dev do
+      cmd("yarn", ~w(run build))
+    end
+  end
+
+  defp cmd(cmd, args, opts \\ []) do
+    opts = Keyword.merge([into: IO.stream(:stdio, :line), stderr_to_stdout: true], opts)
+    {_, result} = System.cmd(cmd, args, opts)
+
+    if result != 0 do
+      raise "Non-zero result (#{result}) from: #{cmd} #{Enum.map_join(args, " ", &inspect/1)}"
+    end
   end
 end

yarn.lock

@@ -2364,9 +2364,9 @@ hawk@~6.0.2:
     hoek "4.x.x"
     sntp "2.x.x"
 
-highlight.js@isagalaev/highlight.js#9.12.0:
+highlight.js@elixir-lang/highlight.js#278960a2ca:
   version "9.12.0"
-  resolved "https://codeload.github.com/isagalaev/highlight.js/tar.gz/16ab6f3b5f9a432e6e8825807103b6bb5cefef15"
+  resolved "https://codeload.github.com/elixir-lang/highlight.js/tar.gz/278960a2ca269fab9aad39dfe1a9dccbb0bd6027"
 
 hoek@0.9.x:
   version "0.9.1"