Packages

earmark

0.1.5
1.5.0-pre1 retired 1.5.0-pre retired 1.4.49 retired 1.4.48 retired 1.4.47 retired 1.4.46 retired 1.4.45 retired 1.4.44 retired 1.4.43 retired 1.4.42 retired 1.4.41 retired 1.4.40 retired 1.4.39 retired 1.4.38 retired 1.4.37 retired 1.4.36 retired 1.4.35 retired 1.4.34 retired 1.4.33 retired 1.4.32 retired 1.4.31 retired 1.4.30 retired 1.4.29 retired 1.4.28 retired 1.4.27 retired 1.4.26 retired 1.4.25 retired 1.4.24 retired 1.4.23 retired 1.4.22 retired 1.4.21 retired 1.4.20 retired 1.4.19 retired 1.4.18 retired 1.4.17 retired 1.4.16 retired 1.4.16-pre2 retired 1.4.16-pre1 retired 1.4.16-pre retired 1.4.15 retired 1.4.14 retired 1.4.13 retired 1.4.12 retired 1.4.10 retired 1.4.9 retired 1.4.8 retired 1.4.7 retired 1.4.6 retired 1.4.5 retired 1.4.4 retired 1.4.3 retired 1.4.2 retired 1.4.1 retired 1.4.0 retired 1.3.6 retired 1.3.5 retired 1.3.4 retired 1.3.3 retired 1.3.2 retired 1.3.1 retired 1.3.0 retired 1.2.6 retired 1.2.5 retired 1.2.4 retired 1.2.3 retired 1.2.2 retired 1.2.1 retired 1.2.0 retired 1.1.1 retired 1.1.0 retired 1.0.3 retired 1.0.2 retired 1.0.1 retired 1.0.0 retired 0.2.1 retired 0.2.0 retired 0.1.19 retired 0.1.18 retired 0.1.17 retired 0.1.16 retired 0.1.15 retired 0.1.14 retired 0.1.13 retired 0.1.12 retired 0.1.10 retired 0.1.9 retired 0.1.8 retired 0.1.7 retired 0.1.6 retired 0.1.5 retired 0.1.4 retired 0.1.3 retired 0.1.2 retired 0.1.1 retired 0.1.0 retired

Earmark is a pure-Elixir Markdown converter. It is intended to be used as a library (just call Earmark.as_html), but can also be used as a command-line tool (run mix escript.build first). Output generation is pluggable.

Retired package: Deprecated - Earmark is no longer maintained. Migrate to a replacement, for example MDEx (https://hex.pm/packages/mdex).
HexDocs

Current section

Files

Jump to
Readme
95 Versions
0 Dependencies
114 Dependants
1 Advisory
Files
Activity
earmark tasks readme.exs
Raw

tasks/readme.exs 

defmodule Mix.Tasks.Readme do

  use Mix.Task



  @shortdoc "Build README.md by including module docs"



  @moduledoc """

  Imagine a README.md that contains



      # Overview



      <!-- moduledoc: Earmark -->



      # Typical calling sequence



      <!-- doc: Earmark.to_html -->



  Run this task, and the README will be updated with the appropriate

  documentation. Markers are also added, so running it again

  will update the doc in place.

  """



  def run([]) do

    Mix.Task.run "compile", []

    File.read!("README.md")

    |> remove_old_doc

    |> add_updated_doc

    |> write_back

  end



  @new_doc ~R/(\s* <!-- \s+ (module)?doc: \s* (\S+?) \s+ -->).*\n/x



  @existing_doc ~R/

     (?:^|\n+)(\s* <!-- \s+ (module)?doc: \s* (\S+?) \s+ -->).*\n

     (?: .*?\n )+?

     \s* <!-- \s end(?:module)?doc: \s+ \3 \s+ --> \s*?

  /x



  defp remove_old_doc(readme) do

    Regex.replace(@existing_doc, readme, fn (_, hdr, _, _) -> 

        hdr 

    end)

  end



  defp add_updated_doc(readme) do

    Regex.replace(@new_doc, readme, fn (_, hdr, type, name) -> 

      "\n" <> hdr <> "\n" <> 

      doc_for(type, name) <> 

      Regex.replace(~r/!-- /, hdr, "!-- end") <> "\n"

    end)

  end



  defp doc_for("module", name) do

    module = String.to_atom("Elixir." <> name)



    docs = case Code.ensure_loaded(module) do

      {:module, _} ->

        if function_exported?(module, :__info__, 1) do

          case Code.get_docs(module, :moduledoc) do

            {_, docs} when is_binary(docs) ->

              docs

            _ -> nil

          end

        else

          nil

        end

      _ -> nil

    end



    docs # || "No module documentation available for #{name}\n"

  end



  defp doc_for("", name) do

    names = String.split(name, ".")

    [ func | modules ] = Enum.reverse(names)

    module = Enum.reverse(modules) |> Enum.join(".")

    module = String.to_atom("Elixir." <> module)

    func   = String.to_atom(func)



    markdown = case Code.ensure_loaded(module) do

      {:module, _} ->

        if function_exported?(module, :__info__, 1) do

          docs = Code.get_docs(module, :docs)

          doc = Enum.find(docs, fn ({{fun, _}, _line, _kind, _args, _doc}) ->

            fun == func

          end)

          {_fun, _line, _kind, _args, documentation} = doc

          documentation

        else

          nil

        end

      _ -> nil

    end



    markdown || "No function documentation available for #{name}\n"

  end



                                                      

  defp write_back(readme) do

    IO.puts :stderr,

      (case File.write("README.md", readme) do

        :ok -> "README.md updated"

        {:error, reason} ->

           "README.ms: #{:file.explain_error(reason)}"

      end)

  end

end