{"id":20778286,"url":"https://github.com/jelly-beam/rebar3_ex_doc","last_synced_at":"2025-12-12T00:24:53.302Z","repository":{"id":37299395,"uuid":"439969875","full_name":"jelly-beam/rebar3_ex_doc","owner":"jelly-beam","description":"rebar3 plugin for generating docs with ex_doc","archived":false,"fork":false,"pushed_at":"2024-12-15T18:13:49.000Z","size":346,"stargazers_count":43,"open_issues_count":2,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-16T06:47:54.508Z","etag":null,"topics":["rebar3-plugin"],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jelly-beam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-19T21:17:39.000Z","updated_at":"2024-12-15T18:13:24.000Z","dependencies_parsed_at":"2023-12-26T17:03:20.805Z","dependency_job_id":"c307099f-ad32-4180-9cf6-f867621d3e71","html_url":"https://github.com/jelly-beam/rebar3_ex_doc","commit_stats":{"total_commits":84,"total_committers":12,"mean_commits":7.0,"dds":0.3214285714285714,"last_synced_commit":"d3b7b5fd4ed1fbc69f1d6ba72620b5cb461380d6"},"previous_names":["jelly-beam/rebar3_ex_doc","starbelly/rebar3_ex_doc"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jelly-beam%2Frebar3_ex_doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jelly-beam%2Frebar3_ex_doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jelly-beam%2Frebar3_ex_doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jelly-beam%2Frebar3_ex_doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jelly-beam","download_url":"https://codeload.github.com/jelly-beam/rebar3_ex_doc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230568586,"owners_count":18246376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rebar3-plugin"],"created_at":"2024-11-17T13:20:40.260Z","updated_at":"2025-12-12T00:24:53.262Z","avatar_url":"https://github.com/jelly-beam.png","language":"Erlang","funding_links":[],"categories":["Erlang"],"sub_categories":[],"readme":"# rebar3_ex_doc\n\n[![Build Status](https://github.com/starbelly/rebar3_ex_doc/actions/workflows/ci.yml/badge.svg)](https://github.com/starbelly/rebar3_ex_doc/actions/workflows/ci.yml)\n[![Erlang/OTP Versions](https://img.shields.io/badge/erlang%2Fotp-26%7C27%7C28-blue)](http://www.erlang.org)\n[![Hex Version](https://img.shields.io/hexpm/v/rebar3_ex_doc.svg)](https://hex.pm/packages/rebar3_ex_doc)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/rebar3_ex_doc/)\n[![Total Download](https://img.shields.io/hexpm/dt/rebar3_ex_doc.svg)](https://hex.pm/packages/rebar3_ex_doc)\n[![License](https://img.shields.io/hexpm/l/rebar3_ex_doc.svg)](https://github.com/starbelly/rebar3_ex_doc/blob/main/LICENSE)\n[![Last Updated](https://img.shields.io/github/last-commit/starbelly/rebar3_ex_doc.svg)](https://github.com/starbelly/rebar3_ex_doc/commits/main)\n\n`rebar3_ex_doc` is a `rebar3` plugin to generate documentation using [ex\\_doc](https://github.com/elixir-lang/ex_doc). This plugin ships with `ex_doc` as an escript, thus you don't need to worry about having Elixir installed nor compiling the `ex_doc` dependencies.\n\n\u003cdiv style=\"text-align: center;\"\u003e\n  \u003cimg alt=\"Screenshot of rebar3_ex_doc\" src=\"assets/screenshot.png\" /\u003e\n\u003c/div\u003e\n\nThis plugin can be used to generate documentation on its own and also integrates with [rebar3_hex](https://github.com/erlef/rebar3_hex) for publishing documentation to go along with your packages on [hex.pm](https://hex.pm/).\n\n## Installation\n\n**NOTE**: This plugin and more importantly `ex_doc` depend on `edocs` capability to generate beam chunks per [EEP-48](https://www.erlang.org/doc/apps/edoc/doc_storage.html).\n\n## Maintenance window\n\nThe minimum OTP version supported by this plugin is Erlang/OTP 26.\n\n### As a global plugin\n\nSimply add `rebar3_ex_doc` to the plugins section in your global `rebar3.config`:\n\n```erlang\n{plugins, [rebar3_ex_doc]}.\n```\n\n### In your rebar3 project\n\nYou can add this plugin to your rebar3 project as a project plugin, like so:\n\n```erlang\n{project_plugins, [rebar3_ex_doc]}.\n```\n\n## Setup\n\nThis plugin should work out of the box, but the following configuration is recommended when publishing documentation to [hex.pm](https://hex.pm).\n\nSimply add the configuration below to your `rebar.config` and adjust for your project:\n\n```erlang\n{ex_doc, [\n     {extras, [\"README.md\", \"LICENSE\"]},\n     {main, \"README.md\"},\n     {source_url, \"https://github.com/namespace/your_app\"}\n]}.\n```\n\nFor further customization, see the configuration for `rebar3_ex_doc`:\n\n```erlang\n{ex_doc, [\n    {extras, [\n          {\"CHANGELOG.md\", #{title =\u003e \"Changelog\"}},\n          {\"README.md\", #{title =\u003e \"Overview\"}},\n          {\"LICENSE.md\", #{title =\u003e \"License\"}}\n    ]},\n    {main, \"README.md\"},\n    {homepage_url, \"https://github.com/starbelly/rebar3_ex_doc\"},\n    {source_url, \"https://github.com/starbelly/rebar3_ex_doc\"},\n    {assets, \"assets\"},\n    {api_reference, false}\n]}.\n```\n\nPlease see the `ex_doc` [configuration documentation](https://hexdocs.pm/ex_doc/Mix.Tasks.Docs.html#module-configuration) for a complete overview of available configuration directives.\nNote that `\"assets\"` can be replaced with a map from source to target directories.\n\nYou may also use an external config file by specifying a path instead of a proplist. See `ex_doc --help` for more info.\n\n```erlang\n%% In Elixir format\n{ex_doc, \"docs.exs\"}.\n\n%% Or in Erlang term, like rebar.config\n{ex_doc, \"docs.config\"}.\n```\n\n### Umbrella support\n\nUmbrellas are supported but they must be configured on an app by app basis. This is to avoid publishing documentation to Hex.pm with wrong source urls, logos, etc.\n\nSpecifically, for each app you wish to generate documentation for, and more importantly publish to hex.pm, you should place a `rebar.config` in each app directory with the desired configuration for that application.\n\n## Usage\n\nAfter the plugin has been added to your project you can simplly run `rebar3 ex_doc` to generate your docs and view them in your favorite browser.\n\nRun `rebar3 help ex_doc` to see all available options.\n\n### Integrating with rebar3_hex\n\nWe highly recommend using `rebar3_ex_doc` as the documentation provider for all your hex projects to provide the users of our ecosystem with a consistent documentation format and style.\n\nTo integrate with `rebar3_hex` merely specify `rebar3_ex_doc` as the doc provider in your projects hex configuration in `rebar.config` :\n\n```erlang\n{hex, [\n    {doc, #{provider =\u003e ex_doc}}\n]}.\n```\n\n#### packages\n\nrebar3_ex_doc optimizes for applications intended to be published to [hex.pm](https://hex.pm) such that\nthe application name is passed to ex_doc by default as the value to the package option.\n\nIf you wish to generate documentation outside the context of a package you may specify `{package, false}` in the options :\n\n```erlang\n{ex_doc, [\n     {package, false},\n     {extras, [\"README.md\", \"LICENSE\"]},\n     {main, \"README.md\"},\n     {source_url, \"https://github.com/namespace/your_app\"}\n]}.\n```\n\n### Supported options\n\nNot all `ex_doc` options are supported. This means we'll warn on unknown options, but still pass them to `ex_doc`. We try to make sure the supported options are converted to the format known by `ex_doc`.\nIn case you get a warning for something that is working or would like further conversion support, open a [GitHub issue](https://github.com/starbelly/rebar3_ex_doc/issues).\n\n### Additional options\n\n#### Support for Mermaid\n\nOut-of-the-box support for [Mermaid](https://mermaid.js.org/) is provided via `rebar.config` option\n`with_mermaid`, as follows:\n\n```erlang\n{ex_doc, [\n     {with_mermaid, true}\n]}.\n```\n\nor\n\n```erlang\n{ex_doc, [\n     {with_mermaid, \"10.2.4\"}\n]}.\n```\n\nCheck out what this looks like in `doc/index.html`.\n\n```mermaid\ngraph TD;\n    A--\u003eB;\n    A--\u003eC;\n    B--\u003eD;\n    C--\u003eD;\n```\n\n#### v prefix for source ref versions\n\nBy default rebar3_ex_doc adopts the convention of prefixing versions with `v`.\nIf your project doesn't follow this convention you may opt out of it with `{prefix_ref_vsn_with_v, false}`\n\n```erlang\n{ex_doc, [\n     {prefix_ref_vsn_with_v, false},\n     {extras, [\"README.md\", \"LICENSE\"]},\n     {main, \"README.md\"},\n     {source_url, \"https://github.com/namespace/your_app\"}\n]}.\n```\n\n### Examples\n\nCheck out our [examples](https://github.com/starbelly/rebar3_ex_doc/tree/main/examples) directory in this repository for working project examples.\n\n### Extras\n\nExDoc [extras](https://hexdocs.pm/ex_doc/readme.html#additional-pages) are additional pages of content written in Markdown. When used with `rebar3_ex_doc`, Erlang syntax is supported for auto-link references with ExDoc prefixes (`c:` and `t:`):\n\n* Modules: `module`\n* Functions: `function/1`, `module:function/1`\n* Callbacks: `c:handle_call/3`, `c:gen_server:handle_call/3`\n* Types: `t:nullary_type()`, `t:type_with_parameter/1`\n\n# Development\n\nIf you'd like to hack on this plugin, follow the steps below:\n\n1. You must have at least Elixir 1.13.0\n   [installed](https://elixir-lang.org/install.html) to build the `ex_doc`\n   escript.\n\n2. Make a new rebar project or go into an existing project:\n\n    ```bash\n    rebar3 new myapp\n    cd myapp\n    ```\n\n3. Make a `_checkouts` directory:\n\n    ```bash\n    mkdir _checkouts\n    ```\n\n4. Go to `_checkouts` and clone this repository to create a\n   [checkout dependency](http://rebar3.org/docs/configuration/dependencies/#checkout-dependencies):\n\n    ```bash\n    cd _checkouts\n    git clone https://github.com/starbelly/rebar3_ex_doc\n    ```\n\n5. Get all dependencies and build the `ex_doc` console app:\n\n    ```bash\n    cd rebar3_ex_doc\n    mix deps.get\n    mix escript.build\n    ```\n\n6. Go back to the root of your project:\n\n    ```bash\n    cd ../..\n    ```\n\n7. Add `rebar3_ex_doc` as plugin to your `rebar.config`:\n\n    ```erlang\n    {project_plugins, [rebar3_ex_doc]}.\n    ```\n\n8. Generate documentation as an initial test:\n\n    ```bash\n    rebar3 ex_doc\n    ```\n\n## Copyright and License\n\nCopyright 2021, Bryan Paxton \u003cbryan@starbelly.io\u003e.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0).\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjelly-beam%2Frebar3_ex_doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjelly-beam%2Frebar3_ex_doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjelly-beam%2Frebar3_ex_doc/lists"}