1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\" Modified by Sergei Golovan
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "EX_DOC 1"
.TH EX_DOC 1 "2024\-03\-02" "0.31.1+dfsg\-1" "ExDoc for Debian GNU/Linux"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ex_doc \- generate Elixir/Erlang documentation from sources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBex_doc\fR PROJECT VERSION BEAMS [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
ExDoc is a tool to generate documentation for Erlang and Elixir projects. To see an example, [you can access Elixir's official docs](https://hexdocs.pm/elixir/).
.SH "FEATURES"
.IX Header "FEATURES"
ExDoc ships with many features:
.PP
* Automatically generates online- and offline-accessible HTML and EPUB documents from your API documentation.
* Responsive design, covering phones and tablets.
* Support for custom pages, guides, livebooks and cheatsheets.
* Support for custom grouping of modules, functions, and pages in the sidebar.
* Customizable logo.
* A direct link back to the source code for every documented entity.
* Full-text search.
* Keyboard shortcuts. (Press `?` to show help.)
* Quick-search with autocompletion support. (`s` keyboard shortcut.)
* Go-to shortcut with auto-complete to take the reader to any HexDocs package documentation. (`g` keyboard shortcut.)
* Support for night mode, activated according to the browser preference.
* Tooltips for links to modules and functions, both for the current project and other projects.
* Version dropdown, automatically configured when hosted on HexDocs.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fBPROJECT\fR" 4
.IX Item "PROJECT"
Project name.
.IP "\fBVERSION\fR" 4
.IX Item "VERSION"
Version number.
.IP "\fBBEAMS\fR" 4
.IX Item "BEAMS"
Path to compiled beam files.
.IP "\fB\-\-canonical\fR" 4
.IX Item "--canonical"
Indicate the preferred URL with rel="canonical" link element.
.IP "\fB\-c\fR, \fB\-\-config\fR" 4
.IX Item "-c, --config"
Give configuration through a file instead of a command line. See "Custom config" section below for more information.
.IP "\fB\-f\fR, \fB\-\-formatter\fR" 4
.IX Item "-f, --formatter"
Docs formatter to use (html or epub), default: html and epub.
.IP "\fB\-\-homepage-url\fR" 4
.IX Item "--homepage-url"
URL to link to for the site name.
.IP "\fB\-\-language\fR" 4
.IX Item "--language"
Identify the primary language of the documents, its value must be a valid [BCP 47](https://tools.ietf.org/html/bcp47) language tag, default: "en".
.IP "\fB\-l\fR, \fB\-\-logo" 4
.IX Item "-l, --logo"
Path to the image logo of the project (only PNG or JPEG accepted) The image size will be 64x64 and copied to the assets directory.
.IP "\fB\-m\fR, \fB\-\-main" 4
.IX Item "-m, --main"
The entry-point page in docs, default: "api-reference".
.IP "\fB\-o\fR, \fB\-\-output" 4
.IX Item "-o, --output"
Path to output docs, default: "doc".
.IP "\fB\-\-package" 4
.IX Item "--package"
Hex package name.
.IP "\fB\-\-paths" 4
.IX Item "--paths"
Prepends the given path to Erlang code path. The path might contain a glob pattern but in that case, remember to quote it: --paths "_build/dev/lib/*/ebin". This option can be given multiple times.
.IP "\fB\-\-proglang" 4
.IX Item "--proglang"
The project's programming language, default: "elixir".
.IP "\fB\-q\fR, \fB\-\-quiet" 4
.IX Item "-q, --quiet"
Only output warnings and errors.
.IP "\fB\-\-source-ref" 4
.IX Item "--source-ref"
Branch/commit/tag used for source link inference, default: "master".
.IP "\fB\-u\fR, \fB\-\-source-url" 4
.IX Item "-u, --source-url"
URL to the source code.
.IP "\fB\-v\fR, \fB\-\-version" 4
.IX Item "-v, --version"
Print ExDoc version.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.PP
ex_doc "Ecto" "0.8.0" "_build/dev/lib/ecto/ebin" -u "https://github.com/elixir-ecto/ecto"
.PP
ex_doc "Project" "1.0.0" "_build/dev/lib/project/ebin" -c "docs.exs"
.SH "CUSTOM CONFIG"
.IX Header "CUSTOM CONFIG"
A custom config can be given with the `--config` option.
.PP
The file must either have ".exs" or ".config" extension.
.PP
The file with the ".exs" extension must be an Elixir script that returns a keyword list with
the same options declares in `Mix.Tasks.Docs`. Here is an example:
[
extras: Path.wildcard("lib/elixir/pages/*.md"),
groups_for_docs: [
Guards: & &1[:guard] == true
],
skip_undefined_reference_warnings_on: ["compatibility-and-deprecations"],
groups_for_modules: [
...
]
]
.PP
The file with the ".config" extension must contain Erlang terms separated by ".".
See `:file.consult/1` for more information. Here is an example:
{extras, [<<"README.md">>, <<"CHANGELOG.md">>]}.
{main, <<"readme">>}.
{proglang, erlang}.
.SH "SOURCE LINKING"
.IX Header "SOURCE LINKING"
ExDoc by default provides links to the source code implementation as
long as `--source-url` or `--source-url-pattern` is provided. If you
provide `--source-url`, ExDoc will inflect the url pattern automatically
for GitHub, GitLab, and Bitbucket URLs. For example:
--source-url "https://github.com/elixir-ecto/ecto"
.PP
Will be inflected as:
https://github.com/elixir-ecto/ecto/blob/master/%{path}#L%{line}
.PP
To specify a particular branch or commit, use the `--source-ref` option:
--source-url "https://github.com/elixir-ecto/ecto" --source-ref "v1.0"
.PP
will result in the following URL pattern:
https://github.com/elixir-ecto/ecto/blob/v1.0/%{path}#L%{line}
.SH "AUTHORS"
.IX Header "AUTHORS"
Plataformatec & The Elixir Team.
|
