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
|
[[!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
Pad:
- Q1: Sorry if you already answered this somewhere (but if not, can
someone with a reddit account copy this over? thx). Hi, I would love
to move my team over to using something org-based, but that\'ll
never happen because, well\... (wait for it) Emacs! By the way, I\'m
currently using heavily customized Sphinx setup, mostly internal,
sometimes shared with data partners; lots of schema-gen from message
protocols defined in code, etc. Anyhow: questions. Do you work with
non-Emacs users? If so, how did you get them to accept this
workflow? And if it\'s just you DJ\'ing, how do they weigh in when
they want an update, open a formal ticket?
- <https://github.com/jypma/emacsconf2021/blob/master/presentation.org>
BBB:
- Have you encountered any push-back from people requesting the documentation who are of the opinion that only a Word document will do?
- Jan: Not really, I tend to deliver the PDFs only. If more is needed, I expect I'd make a docker container with emacs in it, so people can export the org-file to PDF themselves.
- The main problem I have is that effectively they end up branching it in order to use Word's change tracking, and there is no reverse path.
- Jan: That sounds more like a team thing. Most people I interact with are developers, and are OK reading/interpreting change tracking as a git diff, e.g. on github or azure devops.
- OK, thanks. I think that is the root of my problem I just thought I would ask in-case you had encountered the same. Thank you for the talk.
- Jan: I think in your case I'd either introduce them to a nice web-based git interface (org-mode looks fine usually), so they see it can do similar things as word change tracking.
- Jan: Thanks for your feedback :) feel free to reach out if you want to chat more.
- Unfortunately in this case they refuse to use anything that isn't a WYSIWYG interface. So even a Markdown editor in a split screen with a preview window is not accepted.
- Thanks!
- Jan: Hold their hands, be kind, small baby steps :)
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
|
