ExDoc 安装与配置指南

ExDoc 安装与配置指南

ex_doc ExDoc produces HTML and EPUB documentation for Elixir projects 项目地址: https://gitcode.com/gh_mirrors/ex/ex_doc

1. 项目基础介绍

ExDoc 是一个用于为 Erlang 和 Elixir 项目生成文档的工具。它能够从 API 文档中自动生成离线可访问的 HTML 和 EPUB 文档。ExDoc 拥有响应式设计，适用于手机和平板电脑，同时支持自定义页面、指南、实时书籍和备忘录等功能。

主要编程语言：Elixir 和 Erlang

2. 项目使用的关键技术和框架

• Elixir：一种功能强大的函数式编程语言，用于构建可扩展和容错的应用程序。
• Erlang：一种用于构建并行、分布式、容错应用的编程语言。
• Makeup：用于语法高亮的库，ExDoc 使用它来为代码提供语法高亮显示。
• EDoc：Erlang 的文档生成器，ExDoc 在处理 Erlang 项目时使用它。

3. 项目安装和配置的准备工作与详细步骤

准备工作

在开始安装 ExDoc 之前，请确保您已经满足了以下先决条件：

• 安装了 Elixir（版本 1.12 或更高）。
• 对于 Erlang 项目，确保安装了 Erlang 开发环境（例如，在 Debian 系统中运行 sudo apt install erlang-dev）。
• 如果是 Elixir 项目，需要在项目的 mix.exs 文件中添加 ExDoc 作为依赖。

详细安装步骤

对于 Elixir 项目：

1. 在项目根目录下编辑 mix.exs 文件，添加 ExDoc 依赖：

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

2. 运行 mix deps.get 来获取 ExDoc 和其他依赖。

3. 配置 ExDoc，可以在 mix.exs 文件中添加以下配置：

   def project do
     [
       app: :my_app,
       version: "0.1.0-dev",
       # Docs
       name: "MyApp",
       source_url: "https://github.com/USER/PROJECT",
       homepage_url: "http://YOUR_PROJECT_HOMEPAGE",
       docs: &docs/0
     ]
   end
   
   defp docs do
     [
       main: "MyApp",
       # The main page in the docs
       logo: "path/to/logo.png",
       extras: ["README.md"]
     ]
   end
   

4. 运行 mix docs 来生成文档。

对于 Erlang 项目：

1. 使用 Rebar3 来安装 ExDoc。

2. 按照官方文档中的指引配置 Rebar3 来使用 ExDoc。

使用命令行：

1. 安装 ExDoc 为 escript：

   mix escript.install hex ex_doc
   

2. 进入项目目录并编译项目：

   cd PATH_TO_YOUR_PROJECT
   mix compile
   

3. 运行 ExDoc 可执行文件，提供项目名称、版本、ebin 目录、主模块、GitHub 用户和仓库链接以及 logo 路径：

   ex_doc "PROJECT_NAME" "PROJECT_VERSION" "_build/dev/lib/project/ebin" -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png
   

以上步骤将帮助您成功安装和配置 ExDoc，从而为您的项目生成专业的文档。

ex_doc ExDoc produces HTML and EPUB documentation for Elixir projects 项目地址: https://gitcode.com/gh_mirrors/ex/ex_doc