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
|
[[!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
[[!inline pages="internal(2021/info/tech-schedule)" raw="yes"]]
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.
The session will show how leverage org-babel, restclient and
org-treeslide to write and present technical documentation with style.
# Discussion
IRC nick: jan-ypma
- I use restclient everyday, but never thought about using it from code blocks, duh! Very interesting talk!
- This is a good demo, I've found org-babel to be a really amazing glue language for stuff that's sort of annoying to automate otherwise.
- Thanks! :) So the fonts of the current talk are: Fixed pitch (serif): New Heterodox Mono, Variable pitch (serif): ETBembo
- for live coding presentations, demo-it is also pretty cool
- indeed, i have been trying to work out literate devops through org documents. Very cool and useful in specific contexts atleast I guess. like finding the status of a service quickly right within a structured org document.
# Outline
- Introduction
- Demo: Developer guide
- Demo: REST API guide
- Demo: Presentations
- Used packages and configuration
[[!inline pages="internal(2021/captions/tech)" raw="yes"]]
[[!inline pages="internal(2021/info/tech-nav)" raw="yes"]]
# Speaker profile
Jan Ypma is an independent software architect and developer, specializing on the Java platform, functional
programming and distributed systems.
Name pronunciation: Jan EEP-mah
Pronouns: he/his
Preferred contact info: jan@ypmania.net
|
