ExDoc

Mix.install([
  {:jason, "~> 1.4"},
  {:kino, "~> 0.8.0", override: true},
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"}
])

Navigation

Return Home Report An Issue

Setup

Ensure you type the ea keyboard shortcut to evaluate all Elixir cells before starting. Alternatively you can evaluate the Elixir cells as you read.

ExDoc

ExDoc takes the documentation we define in our project using @moduledoc and @doc and generates the same documentation we’ve see on HexDocs.

To add ExDoc to a mix project, we install it in our list of dependencies in mix.exs. The latest version is on hex.pm. We only need documentation for the :dev environment, and we do not need it during runtime.

  defp deps do
    [
      {:ex_doc, "~> 0.28", only: :dev, runtime: false}
    ]
  end

Install dependencies.

$ mix deps.get

Then generate documentation for the project.

$ mix docs

This creates a docs/ folder. Inside the docs folder is an index.html file. HTML stands for hyper-text-markup-language. It’s the code used to structure a web page and its content.

You can open the docs/index.html file in your browser to view the project documentation.

Your Turn

Previously you converted a Math module into a mix project in the ExUnit with Mix section.

Add ExDoc to your Math project. When finished, Open the index.html file in your browser, and you should see a page similar to the following.

Mark As Completed

file_name = Path.basename(Regex.replace(~r/#.+/, __ENV__.file, ""), ".livemd")

save_name =
  case Path.basename(__DIR__) do
    "reading" -> "exdoc_reading"
    "exercises" -> "exdoc_exercise"
  end

progress_path = __DIR__ <> "/../progress.json"
existing_progress = File.read!(progress_path) |> Jason.decode!()

default = Map.get(existing_progress, save_name, false)

form =
  Kino.Control.form(
    [
      completed: input = Kino.Input.checkbox("Mark As Completed", default: default)
    ],
    report_changes: true
  )

Task.async(fn ->
  for %{data: %{completed: completed}} <- Kino.Control.stream(form) do
    File.write!(
      progress_path,
      Jason.encode!(Map.put(existing_progress, save_name, completed), pretty: true)
    )
  end
end)

form

Commit Your Progress

Run the following in your command line from the curriculum folder to track and save your progress in a Git commit. Ensure that you do not already have undesired or unrelated changes by running git status or by checking the source control tab in Visual Studio Code.

$ git checkout -b exdoc-reading
$ git add .
$ git commit -m "finish exdoc reading"
$ git push origin exdoc-reading

Create a pull request from your exdoc-reading branch to your solutions branch. Please do not create a pull request to the DockYard Academy repository as this will spam our PR tracker.

DockYard Academy Students Only:

Notify your teacher by including @BrooklinJazz in your PR description to get feedback. You (or your teacher) may merge your PR into your solutions branch after review.

If you are interested in joining the next academy cohort, sign up here to receive more news when it is available.

Up Next