https://github.com/vkatsuba/rebar3_edoc_extensions
Plugin for custom style of Erlang documentation
https://github.com/vkatsuba/rebar3_edoc_extensions
erlang rebar3 rebar3-plugin
Last synced: 3 months ago
JSON representation
Plugin for custom style of Erlang documentation
- Host: GitHub
- URL: https://github.com/vkatsuba/rebar3_edoc_extensions
- Owner: vkatsuba
- License: apache-2.0
- Created: 2021-11-15T11:58:08.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-11T15:45:11.000Z (9 months ago)
- Last Synced: 2025-03-23T22:47:39.052Z (3 months ago)
- Topics: erlang, rebar3, rebar3-plugin
- Language: Erlang
- Homepage:
- Size: 85.9 KB
- Stars: 9
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# rebar3_edoc_extensions
[![Hex.pm Version][hexpm version]][hexpm]
[![Hex.pm Downloads][hexpm downloads]][hexpm]
[![Hex.pm Documentation][hexdocs documentation]][hexdocs]
[![Erlang Versions][erlang version badge]][gh]
[![Build Status][gh badge]][gh]
`rebar3_edoc_extensions` is a Rebar 3 plugin bringing improvements to
[EDoc](https://www.erlang.org/doc/apps/edoc/chapter.html)-based documentation.
## Getting started
To use this plugin for your project, simply add the plugin to the
`project_plugins` list in your `rebar.config` configuration:
```erlang
%% In `rebar.config`.
{project_plugins, [rebar3_edoc_extensions]}.
```
It overrides the defaut behavior of the `rebar edoc` command. Therefore, the
next time you generate the documentation, you will benefit from the
improvements brought by this plugin.
## EDoc improvements
Here is a list of changes this plugin makes to EDoc-generated documentation:
1. A table of content of the Overview page is added to the left sidebar.
2. The [GitHub Markdown stylesheet](https://github.com/sindresorhus/github-markdown-css)
is used to style the entire documentation.
3. [PrismJS](https://prismjs.com/) is used to enable syntax highlighting to
literals and code snippets.
## Configuration
The plugin supports a few options to configure the **PrismJS syntax
highlighting** library:
* Select the version of PrismJS to download:
```erlang
{prismjs_version, "v1.26.0"}.
```
The default version is `"v1.26.0"`.
* Select the PrismJS theme:
```erlang
{prismjs_theme, "twilight"}.
```
The default theme is `"default"`.
* Select the list of languages to support:
```erlang
{prismjs_languages, ["erlang", "javascript"]}.
```
The default languages are `"erlang"` and `"elixir"`.
## Build
```sh
$ rebar3 compile
```
## Use
Add the plugin to your rebar config:
For generate `doc` with new style, run:
```sh
$ rebar3 edoc
```
[hexpm]: https://hex.pm/packages/rebar3_edoc_extensions
[hexpm version]: https://img.shields.io/hexpm/v/rebar3_edoc_extensions.svg?style=flat-square
[hexpm downloads]: https://img.shields.io/hexpm/dt/rebar3_edoc_extensions.svg?style=flat-square
[hexdocs documentation]: https://img.shields.io/badge/hex-docs-purple.svg?style=flat-square
[hexdocs]: https://hexdocs.pm/rebar3_edoc_extensions
[gh]: https://github.com/vkatsuba/rebar3_edoc_extensions/actions/workflows/ci.yaml
[gh badge]: https://img.shields.io/github/workflow/status/vkatsuba/rebar3_edoc_extensions/CI?style=flat-square
[erlang version badge]: https://img.shields.io/badge/erlang-23.X%20to%2025.X-blue.svg?style=flat-square