You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _posts/2022-12-22-cheatsheets-and-8-other-features-in-exdoc-that-improve-the-developer-experience.markdown
+56-51Lines changed: 56 additions & 51 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,69 +10,66 @@ ExDoc has a cool new feature, [cheatsheets](https://hexdocs.pm/ex_doc/cheatsheet
10
10
11
11
In this blog post, we'll explain what that new feature is and the motivation behind it. We'll also take the opportunity to highlight other ExDoc features that show how it has been evolving to make the documentation experience in Elixir better and better.
12
12
13
-
## What are ExDoc Cheatsheets and how they improve the documentation experience
14
-
ExDoc's Cheatsheets are Markdown files with the `.cheatmd` extension. You can see [an example](https://hexdocs.pm/ecto/crud.html) of how the Ecto project is using them.
13
+
## What are ExDoc cheatsheets and how they improve the documentation experience
15
14
16
-
Writing and reading cheatsheets is not exactly new to developers. What ExDoc brings to the table is the possibility of integrating cheatsheets alongside the rest of the documentation of an Elixir project, instead of hosting it in a different place.
15
+
ExDoc's cheatsheets are Markdown files with the `.cheatmd` extension. You can see [an example](https://hexdocs.pm/ecto/crud.html)of how the Ecto project is using them.
17
16
18
-
Developers need different kinds of docs at different times. When one is learning about a new library, a guide format is proper. When one needs to know if a library can solve a specific problem, an API reference can be more appropriate. When someone wants to remember a couple of functions they already used from that library, a cheatsheet could be more practical.
17
+
Writing and reading cheatsheets is not exactly new to developers. What ExDoc brings to the table is the possibility of integrating cheatsheets alongside the rest of the documentation of an Elixir project, instead of hosting them in a different place.
19
18
20
-
Imagine if you had to go to a different place for every type of documentation you're looking for. That would make a very fragmented experience, not only for readers of documentation but also for writers.
19
+
Developers need different kinds of documentation at different times. When one is learning about a new library, a guide format is proper. When one needs to know if a library can solve a specific problem, an API reference can be more appropriate. When someone wants to remember a couple of functions they already used from that library, a cheatsheet could be more practical.
21
20
22
-
ExDoc Cheatsheets represent one step further in the direction of making documentation in Elixir an even more comprehensive and integrated experience.
21
+
Imagine if you had to go to a different place for every type of documentation you're looking for. That would make a very fragmented experience, not only for readers of documentation but also for writers.
23
22
24
-
ExDoc Cheatsheets are inspired by [devhints.io](https://devhints.io) from [Rico Sta. Cruz](https://twitter.com/rstacruz), and were contributed by [Paulo Valim](https://twitter.com/paulovalim)and [Yordis Prieto](https://twitter.com/alchemist_ubi).
23
+
ExDoc cheatsheets represent one step further in the direction of making documentation in Elixir an even more comprehensive and integrated experience.
25
24
25
+
ExDoc cheatsheets are inspired by [devhints.io](https://devhints.io) from [Rico Sta. Cruz](https://twitter.com/rstacruz), and were contributed by [Paulo Valim](https://twitter.com/paulovalim) and [Yordis Prieto](https://twitter.com/alchemist_ubi).
26
26
27
27
## Eight features that show how ExDoc has improved developer experience over time
28
28
29
-
We added Cheatsheets to ExDoc because we value developer experience and believe documentation is a core aspect of it.
29
+
We added cheatsheets to ExDoc because we value developer experience and believe documentation is a core aspect of it.
30
30
31
31
Since the beginning, one of Elixir's principles is that documentation should be a first-class citizen. What this idea means to us is that documentation should be easy to write and easy to read. ExDoc has been continuously evolving over the years, guided by this principle.
32
32
33
33
Here are some of the features added to ExDoc over the years that make reading and writing documentation in Elixir a joy.
34
34
35
35
### Beautiful and usable design
36
-
As developers, we may not have the skill to make beautifully designed UIs. That doesn't mean we don't appreciate it.
37
36
38
-
Here's what ExDoc-based documentation looked like almost ten years ago, with its original layout based on [YARD](https://yardoc.org/).
37
+
As developers, we may not have the skill to make beautifully designed UIs. That doesn't mean we don't appreciate it. Here's what documentation generated with ExDoc looked like almost ten years ago, with its original layout based on [YARD](https://yardoc.org/):
39
38
40
-
39
+
41
41
42
42
Here's what it looks like today:
43
43
44
-
44
+
45
46
46
-
The evolution of ExDoc's design helped ExDoc-based documentation be more visually appealing and easier to read and navigate.
47
+
The evolution of ExDoc's design helped documentation be more visually appealing and easier to read and navigate.
47
48
48
49
### Links to source code
49
50
50
-
Sometimes you're reading the docs of a library, and you want to know more about the implementation of a function. Or you found something in the documentation that could be improved and wants to help.
51
-
52
-
In those situations, it's helpful to go from the documentation to the source code. ExDoc makes that dead easy.
51
+
Sometimes you're reading the documentation of a library, and you want to know more about the implementation of a function. Or, you found something in the documentation that could be improved and wants to help. In those situations, it's helpful to go from the documentation to the source code. ExDoc makes that dead easy. For every module, function, or page, ExDoc gives you a link that you can click to go directly to the project's source code on GitHub:
53
52
54
-
For every module, function, or page, ExDoc gives you a link that you can click to go directly to the project's source code inside Github:
55
-
56
-
53
+
57
55
58
56
### Guides
59
-
One of the most common formats of library documentation is an API reference. But depending on your needs, that's not the most approachable format. For example,it's not optimal when you're just getting started with a library or when you want to learn how to solve a specific problem using it.
60
57
61
-
That's why ExDoc allows writing other types of docs besides API references, like Getting Started Guides or How-tos.
58
+
One of the most common formats of library documentation is an API reference. But depending on your needs, that's not the most approachable format. For example, it's not optimal when you're just getting started with a library or when you want to learn how to solve a specific problem using it. That's why ExDoc allows writing other types of docs besides API references, like *"Getting started" guides* or *How-tos*.
62
59
63
60
Look at how [Ecto's documentation](https://hexdocs.pm/ecto/getting-started.html) uses that, for example:
64
61
65
-
62
+
66
64
67
65
### Custom grouping of modules, functions, and pages in the sidebar
68
66
69
-
Sometimes your library has dozens of modules. And sometimes, one given module has a large API surface area. In those situations showing the list of functions as a single large list may not be the most digestible way to be consumed.
70
-
71
-
For those situations, ExDoc allows modules, functions, or extra pages to be grouped in the sidebar in a way that makes more sense semantically.
67
+
Sometimes your library has dozens of modules. Sometimes, one given module has a large API surface area. In those situations, showing the list of functions as a single large list may not be the most digestible way to be consumed. For those cases, ExDoc allows modules, functions, or extra pages to be grouped in the sidebar in a way that makes more sense semantically.
72
68
73
69
Here's an example of how Ecto use grouped functions for its `Repo` module:
74
70
75
-
71
+
76
73
77
74
Instead of listing the ~40 functions of `Ecto.Repo` as a single extensive list, it presents them grouped by five cohesive topics:
78
75
@@ -82,45 +79,55 @@ Instead of listing the ~40 functions of `Ecto.Repo` as a single extensive list,
82
79
- Runtime API
83
80
- User callbacks
84
81
85
-
The same functionality is available for modules and pages (guides, how-tos, etc). Phoenix is a [good example](https://hexdocs.pm/phoenix/overview.html) of how that's used.
82
+
The same functionality is available for modules and pages (guides, how-tos, and so on). Phoenix is a [good example](https://hexdocs.pm/phoenix/overview.html) of how that's used.
86
83
87
84
### Full-text search
88
85
89
86
Sometimes you don't know or don't remember the name of the function that you're looking for. For example, let's say you're looking for a function for dealing with file system directories.
90
87
91
88
Although there's no function or module called "directory" in Elixir, when you type "directory" in [Elixir's documentation](https://hexdocs.pm/elixir/search.html?q=directory), it will return all the entries that have the word "directory" inside the documentation. It will even return entries with variations of the word "directory", like "directories", doing a fuzzy search.
92
89
93
-
90
+
94
92
95
93
The search bar also supports autocompletion for module and function names:
96
94
97
-
95
+
98
99
99
-
The best part is that full-text search is fully implemented on the client-side, which means ExDoc pages can be fully hosted as static pages anywhere.
100
+
The best part is that full-text search is fully implemented on the client-side, which means ExDoc pages can be fully hosted as static websites (for example on GitHub Pages).
100
101
101
-
### Keyboard shortcut to navigate to docs of other Hex packages
102
+
### Keyboard shortcuts to navigate to docs of other Hex packages
102
103
103
-
It's usual for an application to have many dependencies. And while coding, we usually need to read the documentation of more than one of those dependencies.
104
+
It's common for an application to have dependencies. While coding, we usually need to read the documentation of more than one of those dependencies.
104
105
105
-
One solution is to keep a window open for each package documentation we need. But ExDoc offers another one, a keyboard shortcut to search and go to another package documentation within the same window.
106
+
One solution is to keep a window open for the documentation of each dependency. However, ExDoc offers another option: a keyboard shortcut to search and go to another package documentation within the same window.
106
107
107
108
Here's what it looks like:
108
109
109
-
110
+
110
113
111
-
And there are more keyboard shortcuts to help you navigate within and between documentation:
114
+
There are more keyboard shortcuts to help you navigate within and between documentation:
112
115
113
-
116
+
114
118
115
119
### A version dropdown to switch to other versions
116
120
117
-
Keeping our application updated with the latest versions of all its dependencies can be challenging. So, it's common to need to look at the documentation of an older version of a library we're using. ExDoc makes it very simple to do that.
121
+
Keeping our application updated with the latest versions of all its dependencies can be challenging. So, it's common to need to look at the documentation of an older version of a library we're using. ExDoc makes it simple to do that.
118
122
119
123
When you access the documentation of a project, there's a dropdown that you can use to select the version you're looking for:
120
124
121
-
125
+
122
128
123
129
### Livebook integration
130
+
124
131
[Livebook](https://livebook.dev/) is a web application for writing interactive and collaborative code notebooks in Elixir.
125
132
126
133
One of the ways Elixir developers have been using Livebook is for documentation. Because of its interactivity capabilities, it enables the reader to play with the code right inside the documentation, which makes it great for tutorials and augmenting the user experience.
@@ -129,21 +136,24 @@ With that in mind, ExDoc offers the possibility of integrating Livebook notebook
129
136
130
137
Here's an [example of using Livebook inside ExDoc for writing a Usage Guide](https://hexdocs.pm/req_sandbox/usage.html):
131
138
132
-
139
+
133
142
134
143
### Bonus: Erlang support
135
144
136
-
[EEP 48](https://www.erlang.org/eeps/eep-0048) proposed a standardized way for how BEAM languages could store API documentation. That allowed any BEAM language to read documentation generated by each other.
145
+
[EEP 48](https://www.erlang.org/eeps/eep-0048) proposed a standardized way for how BEAM languages could store API documentation. This allows any BEAM language to read documentation generated by each other.
137
146
138
-
By leveraging that work, ExDoc can generate docs for an Erlang project. For example, Telemetry is a library written in Erlang that has [its docs](https://hexdocs.pm/telemetry/readme.html) generated with ExDoc.
147
+
By leveraging that work, ExDoc can generate documentation for an Erlang project. For example, Telemetry is a library written in Erlang that has [its documentation](https://hexdocs.pm/telemetry/readme.html) generated with ExDoc.
139
148
140
-
149
+
141
151
142
-
By using ExDoc to also generate docs for Erlang-based projects, we can have more consistency in the user experience along the BEAM ecosystem. See the great [`rebar3_ex_doc`](https://hexdocs.pm/rebar3_ex_doc/) plugin to get started.
152
+
By using ExDoc to also generate documentation for Erlang-based projects, we can have more consistency in the user experience along the BEAM ecosystem. See the great [`rebar3_ex_doc`](https://hexdocs.pm/rebar3_ex_doc/) plugin to get started.
143
153
144
154
### Bonus: Doctests
145
155
146
-
When writing a function's documentation, it's helpful to offer code examples of how that function works. For example, here's the documentation of the `Enum.any?/1` function from Elixir's standard library:
156
+
When writing documentation, it's helpful to offer code examples. For instance, here's the documentation of the `Enum.any?/1` function from Elixir's standard library:
147
157
148
158
```elixir
149
159
@doc """
@@ -166,17 +176,12 @@ immediately and `true` is returned. In all other cases `false` is returned.
166
176
"""
167
177
```
168
178
169
-
To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation. Doctests work by parsing out code samples starting with `iex>` from the documentation.
179
+
To ensure examples do not get out of date, Elixir's test framework ExUnit provides a feature called **doctests**. This allows developers to test the examples in their documentation. Doctests work by parsing out code samples starting with `iex>` from the documentation.
170
180
171
181
Although this is not a feature of ExDoc, it is an essential part of Elixir's developer and documentation experience.
172
182
173
183
## Wrap up
174
184
175
-
As we can see, ExDoc has evolved a lot throughout the years!
176
-
177
-
As it continues to evolve into a more and more comprehensive documentation tool, we want to enable developers to keep investing more time writing the documentation itself instead of needing to spend time building custom documentation tools and websites.
178
-
179
-
The best part is that all you need to do to leverage many of those features is to simply document your code using the `@doc` attribute!
180
-
185
+
As we saw, ExDoc has evolved a lot throughout the years! As it continues to evolve into a more and more comprehensive documentation tool, we want to enable developers to keep investing more time writing the documentation itself instead of needing to spend time building custom documentation tools and websites. The best part is that all you need to do to leverage many of those features is to simply document your code using the `@doc` attribute!
181
186
182
187
Here's to a continuously improving documentation experience for the next years.
0 commit comments