phoenix-framework
Создание проектной документации

обоснование

Правильный вызов вспомогательных модулей и функций может быть пугающим, потому что

• они генерируются динамически (например, при создании нового проекта или добавлении нового resource )
• они не документируются явно (например, MyApp.ErrorHelpers.error_tag )
• документация не охватывает все примеры (например, MyApp.Router.Helpers.*_path в Phoenix.Router ).

Хотя созданные помощники разбросаны по всему вашему проекту, но их расположение следует за твердой логикой. Вы можете привыкнуть к ним довольно быстро и, к счастью, когда вы создаете проект с Phoenix, код поставляется с документацией через @moduledoc модуля @doc и @moduledoc .

Эти документы не ограничиваются только помощниками, но вы также можете

• см. ваш проект, разбитый подмодулями / функциями / макросами
• добавить свою собственную документацию
• найдите любые функции, созданные в пространстве имен вашего проекта (например, MyApp.Repo содержит функции функции обратного вызова из Ecto.Repo )

Создание документов

Чтобы создать документацию из исходного кода, добавьте ex_doc в зависимости от вашего файла mix.exs :

# config/mix.exs

def deps do
  [{:ex_doc, "~> 0.11", only: :dev}]
end

Вы можете использовать Markdown в @doc Elixir @doc и @moduledoc .

Затем запустите mix deps.get чтобы извлечь и скомпилировать новые модули и сгенерировать документацию по проекту с помощью документации по mix docs . Пример вывода - официальные документы Elixir .

Чтобы немедленно их обслуживать, используйте mix docs --output priv/static/doc и перейдите к my_app_url_or_ip/doc/index.html .

Дополнительное чтение:

• ex_doc
• Операторы требований к версии ( Elixir.Version )

Основная часть этого руководства упоминается в рецептах эликсира .