d ocu mentat i on wi t h any e d i tor › 2019 › system › event_attachments › at… ·...
TRANSCRIPT
![Page 1: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/1.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor1
Documentation With Any Editor
Christoph Stoettner
![Page 2: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/2.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor2
Christoph StoettnerApplication Servers
Installation, Configuration
Performance Optimization, Stresstesting
Started with Linux / OSS around 1994/1995
Linux Kernel < 1.0
Slackware
VIM lover
maybe too stupid for Emacs
I’m mainly Administrator using Developer tools
![Page 3: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/3.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor3
My history of documentationContent of most of my documentations
Config options (XML, GUI)
Screenshots (GUI)
Parts of Property Files
Used tools
MS Excel / Libreoffice (with Dropbox)
MS Word / Libreoffice with Sharepoint or Mail
Several Wiki engines, Evernote
LaTex and Docbook
![Page 4: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/4.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor4
My needsSearchable documentation
Editing on mobile, tablet, notebook, customer computer, server (ssh)
Output formats depend on customer and project
Offline support
Version Control
Include config settings of *.xml, *.properties
No manual task to update output format
![Page 5: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/5.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor5
Why did I switch the tools?Evernote
Linux client long time a problem
New license limits device count
No markdown support
Office
Compatibility
Edit on different devices, versions
Sometimes switching printer is enough to flip images around
Copy&Paste of screenshots and config file settings
![Page 6: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/6.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor6
Why not using a wiki?Edit from mobile o�en a pain
Documenting the Wiki itself?
Not accessible when down
Syntax different from one wiki to another
Customer / PM o�en needs something printed / printer friendly
AND manual copy&paste
![Page 7: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/7.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor7
Markdown and rstI started writing in Markdown
Some so�ware supports markdown directly
Cool WYSIWIG editors
Great for typing notes (Still using it on mobile)
But a little bit too simple
including source files missing
![Page 8: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/8.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor8
Asciidoc / Asciidoc: language definition
: Ruby project to convert asciidoc source to * output
Text only, Human readable
Version Control with GIT
Only some short syntax tips
More automation later
Differences to Markdown
Asciidoctor
Asciidoctor
https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/asciidoc-vs-markdown.adoc
![Page 9: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/9.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor9
Doctypes
Article (article) default
One level 0 heading
Book (book)
Additional top-level title as part titles
Man page (manpage)
roff or HTML-formatted man page
Inline (inline)
Use within source-code, e.g. javadoc
:doctype: article|book|manpage|inline
![Page 10: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/10.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor10
H1 only appears once in Asciidoctor article
There can be multiple toplevel headings in:doctype: book
numbered can be set in document header for allheadings
Syntax - Headings1 Headings numbered2 Headings without numbers
:numbered:
== H2
=== H3
==== H4
:!numbered:
== H2
=== H3
==== H4
1
2
![Page 11: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/11.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor11
Headings of blocks and imagesCan be used with images and all kind of blocks, no TOC entry
1 Heading above Code block2 Image heading
.Heading
[source]
----
ls -al
----
.Image
image::test.png[]
1
2
![Page 12: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/12.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor12
Syntax - Lists=== Bullet Points
* Bullet Points
** Sub Bullet Point
=== Numbered Lists
. Numbered List
.. Sub 1
.. Sub 2
. Numbered 2
=== Definition Lists
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system
![Page 13: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/13.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor13
Links
1 Shows just the link2 Link text in brackets
https://www.stoeps.de[]
https://www.stoeps.de[Stoeps]
1
2
![Page 14: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/14.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor14
Images
1 You can add roles to all elements and use CSS for formatting2 One colon a�er image → inline image, double colon → figure
double :
single :
image::sunset.jpg[]
image::sunset.jpg[role=right]
image:sunset.jpg[]
1
2
<div class="imageblock" style=""><img src="images/sunset.jpg" alt="sunset"></div>
<div class="imageblock right" style=""><img src="images/sunset.jpg" alt="sunset"></div>
<div class="paragraph"><p><span class="image"><img src="images/sunset.jpg" alt="sunset"></span></p></div>
![Page 15: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/15.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor15
Use Inline IconsYou can add any Font Awesome Icon
Enable in document header
Some Examples
:icons: font
icon:twitter[] Twitter https://twitter.com[@stoeps]
icon:linux[] Linux Icon
icon:windows[] Windows Icon
![Page 16: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/16.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor16
Admonition BlocksAdmonition blocks (Warning, Caution, Important, Note, Tip)
Font-Awesome Icons with :icons: font
This is a warning
This is a caution
This is important
WARNING: This is a warning
CAUTION: This is a caution
IMPORTANT: This is important
![Page 17: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/17.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor17
Admonition Blocks in Html and PDFNOTE: A note
TIP: Here is a tip
IMPORTANT: That's important
WARNING: Warning message
CAUTION: Caution, be careful
![Page 18: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/18.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor18
Menus, Keys and Buttons
1 Following features need experimental set
Menu, Button, Keys
:experimental: 1
.Copy Text
menu:Edit[Copy Special > Text]
.Button
Press kbd:[OK]
.Keyboard
kbd:[Ctrl+C] to stop this.
![Page 19: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/19.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor19
SourcecodeAdding [source]
Syntax Highlighting with Pygments, Highlightjs or Rouge
.A Python function
[source,python]
----
def function():
var x = 10
return x
----
:source-highlighter: pygments|highlightjs|rouge
![Page 20: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/20.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor20
Including FilesSplit longer documents and include Asciidoc Source
Include any type of files in [source]
Powerful
Include complete files
Include only parts
1 Include entire file2 Include lines 10-153 Include area between mytag tags tag::mytag, end::mytag
include::path/filename[]
include::path/filename[lines=10..15]
include::path/filename[tags=mytag]
1
2
3
![Page 21: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/21.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor21
Example Include
Include in our asciidoc source
Included source
...
<title>example</title>
<!-- tag::stoeps[] -->
<!-- even comments -->
</head><body>
<h1>Test</h1>
<!-- end::stoeps[] -->
</body>
...
[source, indent=0]
----
include::test.html[tags=stoeps]
----
<!-- even comments -->
</head>
<body>
<h1>Test</h1>
![Page 22: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/22.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor22
Callouts in Sources
1 Hardcoded variable
[source]
----
def function:
x = 'secret' # <1>
print(secret)
return 0
----
<1> Hardcoded variable
def function:
x = 'secret'
print(secret)
return 0
1
![Page 23: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/23.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor23
VariablesDefinition
1 Generic definition2 Variable OS set to Linux3 Variable SLASH set to /
Windows Version
Linux Version
:variable: content
:OS: Linux
:SLASH: /
1
2
3
:OS: Windows Server 2016 Datacenter Edition
:SLASH: \
:VERSION: 0.8
:OS: Linux
:SLASH: /
:VERSION: 8.5.5.4
![Page 24: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/24.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor24
Add Variables to extra fileInclude into main document (main.adoc)
Use generic variable file for example to store OS differences
Add additional one for project specific paths, hostnames
1 Main document2 Variables for Linux OS installations3 Variables for Windows installations4 Project specific variables
.
├── _attributes.asciidoc ├── images ├── include ├── main.adoc
├── more.asciidoc ├── _variables-linux.asciidoc
├── _variables_project.asciidoc
└── _variables-win.asciidoc
1
2
4
3
![Page 25: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/25.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor25
Conditional DirectivesWithin main document show different informations based onvariables
1 Set OS = Linux2 If OS = Linux3 Set OS = Windows4 If OS = Windows
:OS: Linux
ifeval::["{OS}" == "Linux"]
icon:linux[] rocks!
endif::[]
:OS: Windows
ifeval::["{OS}" == "Windows"]
icon:windows[] really?
endif::[]
:OS: Linux
1
2
3
4
![Page 26: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/26.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor26
Including Diagrams
supports a lot of different formats
ditaa
plantuml
O�en enough to show a network or infrastructure overview
Like human readable
https://asciidoctor.org/docs/asciidoctor-diagram/
Asciidoctor
Asciidoctor
![Page 27: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/27.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor27
Diagram - ditaa[ditaa]
....
+-------------+
| Asciidoctor |-------+
| diagram | |
+-------------+ | PNG out
^ |
| ditaa in |
| v
+--------+ +--------+----+ /---------------\
|c9CF | --+ Asciidoctor +--> |c9CC |
|Document| +-------------+ | Beautiful |
| {d}| | !magic! | | Output |
+---+----+ +-------------+ \---------------/
....
![Page 28: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/28.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor28
Plantuml [plantuml]
....
title Network Plan
actor user [
User
]
actor admin [
Administrator
]
node http [
HTTP Server
connect.example.com
]
node dmgr [
WebSphere Deployment Manager
dmgr.example.com
]
database db2 [
DB2 Database Server
db2.example.com
]
user -down-> http:443/tcp
admin -right-> dmgr:9043/tcp
admin -down-> db2:50000/tcp
dmgr -up-> http
dmgr -down-> db2
center footer Connections 6.0 Deployment
....
![Page 29: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/29.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor29
Plantuml Simple Flowdiagram[plantuml]
....
start
if (Graphviz installed?) then (yes)
:process all\ndiagrams;
else (no)
:process only
__sequence__ and __activity__ diagrams;
endif
stop
....
![Page 30: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/30.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor30
Tables.Hostnames
[%header, cols=3]
|===
|Hostname
|IP
|Function
|www.example.com
|192.168.1.100
|Webserver
|dmgr.example.com
|192.168.2.100
|Application Server
|db.example.com
|192.168.2.101
|Database Server
![Page 31: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/31.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor31
Putting everything togetherLet’s have a look at a simple document with the main parts
Automate with Gitlab and CI/CD
It’s also possible with Travis CI or Jenkins
Just to have a working example
Asciidoctor gradle
Git (with GitLab)
Gitlab CI/CD functionality
https://gitlab.com/stoeps/gpn19-documentation
![Page 32: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/32.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor32
Main document (main.adoc) - header1 Document title2 Language3 Enable experimental features4 Title logo (for pdf title page)5 Create table of contents6 Default images directory7 Use Font Awesome Icons8 Use rouge for Syntax Highlighting9 Headings numbered10 Translation file for built-in labels, so the labels for
language used in (2) will be inserted
= Example Project Documentation
:author: Christoph Stoettner
:email: [email protected]
:revnumber: 1.0
:revdate: 2018-08-24
:revremark: Froscon 2018
:encoding: utf-8
:lang: en
:experimental:
:title-logo-image: image::logo.png[]
:toc:
:imagesdir: images
:doctype: article
:icons: font
:source-highlighter: rouge
:quick-uri: https://www.stoeps.de
:numbered:
include::_variables-linux.asciidoc[]
include::_variables-project.asciidoc[]
include::_attributes.asciidoc[]
1
2
3
4
5
6
7
8
9
10
![Page 33: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/33.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor33
Attribute (translation of built-in labels)Example for german labels // German translation, courtesy of Florian Wilhelm
ifeval::["{lang}" == "de"]
:appendix-caption: Anhang
:caution-caption: Achtung
:chapter-label: Kapitel
:example-caption: Beispiel
:figure-caption: Abbildung
:important-caption: Wichtig
:last-update-label: Zuletzt aktualisiert
//:listing-caption: Listing
:manname-title: BEZEICHNUNG
:note-caption: Anmerkung
//:preface-title: Vorwort
:table-caption: Tabelle
:tip-caption: Hinweis
:toc-title: Inhalt
:untitled-label: Ohne Titel
:version-label: Version
:warning-caption: Warnung
endif::[]
![Page 34: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/34.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor34
PrefaceFirst paragraph a�er header section
It’s Asciidoc best practise to write each sentence into one line
Paragraph until first blank line
In chapter Networkplan I include a plantuml file
include::_attributes.asciidoc[]
Get tough with it, get strong.
This is the way you take out your flustrations.
Go out on a limb - that's where the fruit is.
If we're gonna walk though the woods, we need a little path.
Trees live in your fan brush, but you have to scare them out.
== Networkplan
![Page 35: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/35.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor35
Conditions to show updated informations === Software Updates
Here we check the `VERSION` from our variables doc.
When we update the main document, it can happen that we adjust the version numbers,
then new generated documents show this warning.
ifeval::["{VERSION}" >= "8.5.5.7"]
INFO: No updates needed!
endif::[]
ifeval::["{VERSION}" < "8.5.5.6"]
WARNING: Update needed!
endif::[]
![Page 36: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/36.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor36
Different Operating SystemsDocumention is splitted into generic parts
Differences
Slash or Backslash
.bat or .sh
Paths
Small differences I handle withifeval::["{variable}" == "OS Type"]
Paths and hostnames are stored in _variables-xxx.asciidoc
So moving to a new version only needs adjustments in main.adoc
![Page 37: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/37.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor37
Including Configuration FilesWorking to get customers to commit configuration to internal gitservers
Adding these repositories to documentation repository
Git Submodules
Git directories within repositories
git add submodule https://internal.gitserver.example.org/appserver/mainconfig.git
![Page 38: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/38.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor38
Build OutputsLots of different Outputs
Html 5
ePub
Docbook
Confluence Wiki
Reveal JS Presentation
A huge amount of outputs:
https://doctoolchain.github.io/docToolchain/
![Page 39: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/39.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor39
Use ThemesYou can build your own themes
HTML
CSS
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc
https://themes.asciidoctor.org
![Page 40: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/40.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor40
EditorsBest: you can use any editor on any device
Syntax Highlighting in the most important ones
VIM
Emacs
Notepad++
VSCode|VSCodium, Atom
On Windows, stay away from Notepad and Wordpad becausethey produce plain text which is not cross-platform friendly.
Documentation on editors
![Page 41: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/41.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor41
MobileI use git for all documents
Version Control
Good mobile clients (for small adjustments)
Android
Termux
Vim
Git
Browser interface (Github, Gitlab)
![Page 42: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/42.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor42
Preview(in the beginning) you will ask for WYSIWIG or Preview
VS Codium has a built-in preview plugin
Check whitelist or you won’t see Font Awesome icons
convert your documents with make
with
Run make everytime when file is saved
Very powerful when you finalize documents or presentations
Browser Extension to render Asciidoc
Makefile
Guardfile Guard
![Page 43: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/43.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor43
Convert your documentsAsciidoctor works on Windows, Linux or Mac
Installation
Ruby Gems or Package Manager
Convert on the command line
You need to install all dependencies
https://asciidoctor.org/docs/install-toolchain/
# Creates HTML of yourfile.adoc, name: yourfile.html
asciidoctor yourfile.adoc
# Create PDF
asciidoctor-pdf yourfile.adoc
![Page 44: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/44.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor44
Docker-Asciidoctor
Easy to use
Runs on all OS which supports Docker
Windows, Linux & Mac OS
All dependencies already included
Fits perfectly into CI/CD scenarios
https://github.com/asciidoctor/docker-asciidoctor
https://hub.docker.com/r/asciidoctor/docker-asciidoctor/
# convert main.doc to html
docker run --rm -v $(pwd):/documents/ asciidoctor/asciidoctor asciidoctor main.adoc
![Page 45: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/45.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor45
Docker command explained
1 delete container a�er run2 Use Volume $(pwd) actual path in Linux and Mac OS as /documents in container3 Image name (template for container)4 Run command asciidoctor in that container5 On document main.adoc
Special command line options can be added!
# Run this in the folder with your asciidoc files
docker run \
--rm \
-v $(pwd):/documents/ \
asciidoctor/asciidoctor \
asciidoctor \
main.adoc
1
2
3
4
5
![Page 46: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/46.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor46
Different Outputs with Docker containerHtml
Html with Diagram
PDF with Diagram
Create page in Confluence Wiki
1 With --update the page gets updated, without created
docker run --rm -v $(pwd):/documents/ asciidoctor/asciidoctor asciidoctor main.adoc
docker run --rm -v $(pwd):/documents/ asciidoctor/asciidoctor asciidoctor -r asciidoctor-diagram main.adoc
docker run --rm -v $(pwd):/documents/ asciidoctor/asciidoctor asciidoctor-pdf -r asciidoctor-diagram main.adoc
asciidoctor-confluence --host HOSTNAME --spaceKey KEY --title TITLE \
--username USER --password PASSWORD [--update] sample.adoc 1
![Page 47: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/47.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor47
Gradle
A full integrated Gradle implementation is used by
Check it out, if you need a full featured solution
Advantage
Downloads all dependencies
Works with DevOps toolsets
Gradle can be used with Gitlab CI/CD, Travis CI and Jenkins
https://github.com/asciidoctor/asciidoctor-gradle-examples
docToolchain
![Page 48: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/48.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor48
CI/CD with GitlabBest result
Hosted ( ) and Selfhosted
Converts on commit
Browse, publish or download results
Deploy the documents to webservers
How to:
Add CI/CD to your Gitlab project
Create .gitlab-ci.yml
https://gitlab.com
![Page 49: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/49.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor49
Repository.
├── docker-asciidoctor (submodule) ├── documents-personal │ ├── basic-example.adoc ├── documents-work │ ├── basic-example.adoc ├── images │ └── logo.png ├── LICENSE ├── pdftheme │ ├── logo.png │ ├── personal-theme.yml │ └── work-theme.yml ├── presentations │ └── slidedeck.adoc
├── public │ ├── html-personal │ ├── html-work │ ├── images │ ├── pdf-personal │ ├── pdf-work │ └── presentations ├── README.adoc ├── scripts │ ├── create-index.sh │ ├── html-conversion.sh │ ├── html-work-conversion.sh │ ├── pdf-conversion.sh │ ├── pdf-work-conversion.sh │ └── reveal-conversion.sh └── wiki-articles
![Page 50: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/50.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor50
.gitlab-ci.yml (1)image: docker:git
services:
- docker:dind
variables:
CONTAINER_TEST_IMAGE: registry.gitlab.com/stoeps/$CI_PROJECT_NAME:$CI_BUILD_REF_NAME
CONTAINER_RELEASE_IMAGE: registry.gitlab.com/stoeps/$CI_PROJECT_NAME:latest
before_script:
- docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com
- git submodule sync --recursive
- git submodule update --init --recursive
stages:
- build
- test
- release
- conversion
- deploy
build:
stage: build
script:
- docker build -t $CONTAINER_TEST_IMAGE docker-asciidoctor
- docker push $CONTAINER_TEST_IMAGE
only:
changes:
- docker-asciidoctor/Dockerfile
refs:
![Page 51: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/51.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor51
.gitlab-ci.yml (2) - master
variables:
- $BUILDCONTAINER
test 1:
stage: test
script:
- echo "Run tests here"
- docker run -t --rm $CONTAINER_TEST_IMAGE asciidoctor -v | grep "Asciidoctor"
only:
changes:
- docker-asciidoctor/Dockerfile
refs:
- master
variables:
- $BUILDCONTAINER
test 2:
stage: test
script:
- docker run -t --rm $CONTAINER_TEST_IMAGE asciidoctor-revealjs -v
only:
changes:
- docker-asciidoctor/Dockerfile
refs:
- master
variables:
- $BUILDCONTAINER
release-image:
![Page 52: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/52.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor52
.gitlab-ci.yml (3) stage: release
script:
- echo "Tag Image and push to registry"
- docker pull $CONTAINER_TEST_IMAGE
- docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
- docker push $CONTAINER_RELEASE_IMAGE
only:
changes:
- docker-asciidoctor/Dockerfile
refs:
- master
variables:
- $BUILDCONTAINER
pdf:personal:
stage: conversion
script:
- echo "Start Asciidoctor conversion"
- echo $CONTAINER_IMAGE:$CI_COMMIT_SHA
- docker run -t --rm -v $(pwd)/documents-personal:/documents/ -v $(pwd)/images:/images -v $(pwd)/scripts:/scripts $CONTAINER_RELEASE_IMAGE /scripts/
- cp documents-personal/*.pdf public/pdf-personal
artifacts:
name: "pdf-personal-$CI_COMMIT_TAG"
paths:
- public/pdf-personal
expire_in: 2 hours
except:
variables:
- $BUILDCONTAINER
![Page 53: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/53.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor53
.gitlab-ci.yml (4)pdf:work:
stage: conversion
script:
- echo "Start Asciidoctor conversion"
- echo $CONTAINER_IMAGE:$CI_COMMIT_SHA
- docker run -t --rm -v $(pwd)/documents-work:/documents/ -v $(pwd)/images:/images -v $(pwd)/scripts:/scripts -v $(pwd)/pdftheme:/pdftheme/ $CONTAIN
- cp documents-work/*.pdf public/pdf-work
artifacts:
name: "pdf-work-$CI_COMMIT_TAG"
paths:
- public/pdf-work
expire_in: 2 hours
except:
variables:
- $BUILDCONTAINER
html:
stage: conversion
script:
- echo "Start Asciidoctor conversion"
- echo $CONTAINER_IMAGE:$CI_COMMIT_SHA
- docker run -t --rm -v $(pwd)/documents-work:/documents/ -v $(pwd)/images:/images -v $(pwd)/scripts:/scripts $CONTAINER_RELEASE_IMAGE /scripts/html
- cp documents-work/*.html public/html-work
- docker run -t --rm -v $(pwd)/documents-personal:/documents/ -v $(pwd)/images:/images -v $(pwd)/scripts:/scripts $CONTAINER_RELEASE_IMAGE /scripts/
- cp documents-personal/*.html public/html-personal
artifacts:
name: "html-$CI_COMMIT_TAG"
paths:
- public/html-work
- public/html-personal
![Page 54: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/54.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor54
.gitlab-ci.yml (5) - images
expire_in: 2 hours
except:
variables:
- $BUILDCONTAINER
reveal:
stage: conversion
script:
- echo "Start Asciidoctor conversion"
- echo $CONTAINER_IMAGE:$CI_COMMIT_SHA
- docker run -t --rm -v $(pwd)/presentations:/documents/ -v $(pwd)/images:/images -v $(pwd)/scripts:/scripts $CONTAINER_RELEASE_IMAGE /scripts/revea
- cp presentations/*.html public/presentations
artifacts:
name: "html-$CI_COMMIT_TAG"
paths:
- public/presentations
- images
expire_in: 2 hours
except:
variables:
- $BUILDCONTAINER
pages:
stage: deploy
dependencies:
- html
- reveal
- pdf:personal
- pdf:work
![Page 55: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/55.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor55
.gitlab-ci.yml (6) script:
- cp -arvf images/* public/images/
- sh scripts/create-index.sh
- chmod +r public -R
artifacts:
paths:
- public
expire_in: 1 hour
only:
refs:
- master # this job will affect only the 'master' branch
except:
variables:
- $BUILDCONTAINER
![Page 56: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/56.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor56
Example conversion script#!/usr/bin/env bash
#
# Author: Christoph Stoettner
#
for i in /documents/*.adoc
do
asciidoctor \
-r asciidoctor-pdf \
-r asciidoctor-diagram \
-r asciidoctor-mathematical \
-b pdf \
-a pdf-stylesdir=/pdftheme \
-a pdf-style=work \
-a media=prepress \
"$i"
done
![Page 57: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/57.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor57
Gitlab Pipeline
1 Build pipeline ran successful2 Failed execution3 Download artifacts (Output formats)
![Page 58: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/58.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor58
Demo
![Page 59: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/59.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor59
Additional informationsThis presentation is build with
Asciidoctor
Reveal.js
Fedora is using Asciidoc for
Based on
Antora creates documentation from multiple git repositories
https://docs.fedoraproject.org/en-US/docs/
Antora
![Page 60: D ocu mentat i on Wi t h Any E d i tor › 2019 › system › event_attachments › at… · Several Wiki engines, Evernote LaTex and Docbook. 4 @ s toep s #FrO SC on14 #D oc umenta](https://reader033.vdocuments.us/reader033/viewer/2022060322/5f0d8fb47e708231d43af80c/html5/thumbnails/60.jpg)
@stoeps #FrOSCon14 #DocumentationWithAnyEditor60
Linkshttps://gitlab.com/stoeps/gpn19-documentation
Asciidoc Syntax Quick Reference
https://doctoolchain.github.io/docToolchain/
Asciidoc Cheatsheet
Using AsciiDoc and Asciidoctor to write documentation
Mr. Haki Blog