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
|
[[!meta title="Creating technical API documentation and presentations using org-babel, restclient, and org-treeslide"]]
[[!meta copyright="Copyright © 2021 Jan Ypma"]]
[[!inline pages="internal(2021/info/tech-nav)" raw="yes"]]
<!-- You can manually edit this file to update the abstract, add links, etc. --->
# Creating technical API documentation and presentations using org-babel, restclient, and org-treeslide
Jan Ypma
The emacs org-babel package is often mentioned in conjunction with
literate programming. The ability to mix code segments with prose
indeed offers an intuitive way to augment semantic code pieces with
textual descriptions.
In recent projects, I've started to turn to org-mode as the primary
format to maintain technical documentation, as well as slides for a
technical language course. By using org-babel to pull in "live" code
for REST requests, language examples, and shell scripts, one can be
sure that the documentation and slides are never out of date.
Two cases are presented:
- API documentation for a REST service (exported from org to html
and PDF)
- Slides for a Java Microservice course (presented within emacs,
handouts in 2 styles as PDF)
The session will show how leverage org-babel, restclient,
org-treeslide, as well as show how to create your own language backend
for org-babel to make sure your own preferred workflow is used.
# Outline
- 5-10 minutes: We'll pick one of the two use cases and briefly show
it and its result.
<!--- 20 minutes: We'll briefly show both use cases.
- 40 minutes: We'll show the details how to combine the mentioned
packages, as well as showing the custom org-babel backend.
-->
[[!inline pages="internal(2021/info/tech-schedule)" raw="yes"]]
[[!inline pages="internal(2021/info/tech-nav)" raw="yes"]]
|
