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!

Installation

Add dry_doc to your list of dependencies in mix.exs, then run mix deps.get:

def deps do
  [
    {:dry_doc, "~> 0.1.0"}
  ]
end

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 DryDoc.from_readme(YourModule)

  @doc DryDoc.from_readme(YourModule, :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 -->

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.