DryDoc

Store all your docs in a README (or a few of them) and pull that content into @moduledoc and @doc annotations at compile time. Then build an entire docs site from there with ex_doc. It seems backwards, but this might just be the cleanest way to maintain a fetching Github repo and hexdocs.pm presence without repeating yourself!

Tip

Also provides styled markdown admonitions / callouts that work when rendered on Github.com AND when published on Hexdocs.pm (ExDoc uses a different syntax from Github).

Installation

Add {:dry_doc, "~> 0.1.2"} to your list of dependencies in mix.exs, then run mix deps.get.

Usage

Write a README.md file. Then, in the module of your choosing, either:

# A. Use the macro:

defmodule YourModule do
  import DryDoc

  @moduledoc doc_from_readme()

  @doc doc_from_readme(:your_func)

  def your_func() do
    ...
  end

  @doc doc_from_file("SOME_OTHER_FILE.md", :your_other_func)

  def your_other_func() do
    ...
  end
end

# B. Call directly:

defmodule YourModule do
  @moduledoc YourModule |> DryDoc.from_readme()

  @doc YourModule |> DryDoc.from_readme(:your_func)

  def your_func() do
    ...
  end

  @doc DryDoc.from_file("SOME_OTHER_FILE.md", YourModule, :your_other_func)

  def your_other_func() do
    ...
  end
end

If you want to pull only certain sections from README.md, use annotations in the README markdown.
The <!-- open --> ... <!-- /close --> backslash scheme should feel familiar to anyone who's written HTML.

# Welcome to my README

<!-- @moduledoc YourModule -->

Only include this content in my @moduledoc.

<!-- /@moduledoc YourModule -->

Not this content.

<!-- @moduledoc YourModule -->

Oh, actually put this content in @moduledoc too.

<!-- /@moduledoc YourModule -->

Bye!

For function docs, add function name after module in the annotations:

# Welcome to my README

<!-- @doc YourModule.your_func -->

This content is for the @doc of the YourModule.your_func function.

<!-- /@doc YourModule.your_func -->

Transformations

Github-flavored Markdown and ExDoc use different syntax for Admonitions, aka "alerts", "callouts", "tips", or "notes". This transformation replaces all Github admonition syntax with an alternate form compatible with ExDoc.

Github<>ExDoc style mappings (imperfect because admonition types don't match):

NOTE      -> .info    (blue)
TIP       -> .tip     (green)
IMPORTANT -> .info    (blue)
WARNING   -> .warning (yellow)
CAUTION   -> .error   (red)

Examples:

Note

This will be displayed as a blue .info on hexdocs.pm

Tip

This will be displayed as a green .tip on hexdocs.pm

Important

This will be displayed as a blue .info on hexdocs.pm

Warning

This will be displayed as a yellow .warning on hexdocs.pm

Caution

This will be displayed as a red .error on hexdocs.pm

References:

• https://ex-doc.hexdocs.pm/readme.html#admonition-blocks
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

Extras

# mix.exs

defmodule YourApp.MixProject do
  ...

  defp docs() do
    [
      ...
+++   before_closing_head_tag: &DryDoc.before_closing_head_tag_hide_pages_tab/1,
    ]
  end
end

For simple projects that don't have any "extras" to live in the "Pages" tab on the generated Hexdocs site, it can feel simpler and clearer to hide this tab entirely. Docs then live in a single place: the @moduledoc of the main module of the project. Add &DryDoc.before_closing_head_tag_hide_pages_tab/1 to your docs() in mix.exs to hide the "Pages" tab.

# mix.exs

defmodule YourApp.MixProject do
  ...

  defp docs() do
    [
      ...
+++   before_closing_body_tag: &DryDoc.before_closing_body_tag_expand_sections_list/1
    ]
  end
end

When your Hexdocs site by default lands on the main project module, and your README is shown there via the @moduledoc, it can be beneficial to auto-expand the "Sections" list in the left sidebar to give a visible "table of contents" of your docs right off the bat (and also let readers easily navigate to a specific section, if they wish). Add &DryDoc.before_closing_body_tag_expand_sections_list/1 to your docs() in mix.exs to automatically expand the "Sections" list on page load and when the sidebar is opened on mobile devices.

Extras Before / After

Prior Art

Inspired by Vapor's moduledoc style, and this forum post pointing to it.

License

MIT