phoenix-framework
Projektdokumentation erstellen

Begründung

Der korrekte Aufruf von Hilfsmodulen und Funktionen kann einschüchternd sein, weil

• Diese werden dynamisch generiert (z. B. beim Erstellen eines neuen Projekts oder Hinzufügen einer neuen resource ).
• Sie werden nicht explizit dokumentiert (z. B. MyApp.ErrorHelpers.error_tag ).
• Die Dokumentation deckt nicht alle Beispiele ab (z MyApp.Router.Helpers.*_path B. MyApp.Router.Helpers.*_path in Phoenix.Router ).

Die erstellten Helfer sind zwar im gesamten Projekt verstreut, ihr Standort folgt jedoch einer festen Logik. Sie können sich recht schnell daran gewöhnen, wenn Sie ein Projekt mit Phoenix generieren. Der Code wird mit der Dokumentation über die Elixir-Attribute @doc und @moduledoc .

Diese Dokumente sind nicht nur auf Helfer beschränkt, sondern auch Sie können dies tun

• sehen Sie Ihr Projekt nach Submodulen / Funktionen / Makros auf
• fügen Sie Ihre eigene Dokumentation hinzu
• MyApp.Repo Funktionen, die im Namensraum Ihres Projekts generiert wurden (z. MyApp.Repo enthält MyApp.Repo Callback-Funktionsimplementierungen von Ecto.Repo ).

Generieren der Dokumente

Um aus Ihrem Quellcode Dokumentation zu generieren, fügen Sie ex_doc als Abhängigkeit in Ihre mix.exs Datei ein:

# config/mix.exs

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

Sie können Markdown in den Attributen Elixir @doc und @moduledoc .

Führen Sie anschließend mix deps.get , um die neuen Module mix deps.get zu kompilieren und die Projektdokumentation mit mix docs generieren. Ein Beispiel für eine Ausgabe sind die offiziellen Elixir Docs .

Um sie sofort zu bedienen, verwenden Sie mix docs --output priv/static/doc und navigieren Sie zu my_app_url_or_ip/doc/index.html .

Zusätzliche Lektüre:

• ex_doc
• Versionsanforderungsoperatoren ( Elixir.Version )

Der Großteil dieses Handbuchs wird aus Elixir-Rezepten referenziert.