d ocu mentat i on wi t h any e d i tor › 2019 › system › event_attachments › at… ·...

Post on 25-Jun-2020

0 Views

Category:

Documents

0 Downloads

Preview:

Click to see full reader

TRANSCRIPT

@stoeps #FrOSCon14 #DocumentationWithAnyEditor1

Documentation With Any Editor

Christoph Stoettner

@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

@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

@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

@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

@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

@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

@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

@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

@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

@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

@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

@stoeps #FrOSCon14 #DocumentationWithAnyEditor13

Links

1 Shows just the link2 Link text in brackets

https://www.stoeps.de[]

https://www.stoeps.de[Stoeps]

1

2

@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>

@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

@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

@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

@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.

@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

@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

@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>

@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

@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

@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

@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

@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

@stoeps #FrOSCon14 #DocumentationWithAnyEditor27

Diagram - ditaa[ditaa]

....

+-------------+

| Asciidoctor |-------+

| diagram | |

+-------------+ | PNG out

^ |

| ditaa in |

| v

+--------+ +--------+----+ /---------------\

|c9CF | --+ Asciidoctor +--> |c9CC |

|Document| +-------------+ | Beautiful |

| {d}| | !magic! | | Output |

+---+----+ +-------------+ \---------------/

....

@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

....

@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

....

@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

@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

@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: christoph.stoettner@stoeps.de

: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

@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::[]

@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

@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::[]

@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

@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

@stoeps #FrOSCon14 #DocumentationWithAnyEditor38

Build OutputsLots of different Outputs

Html 5

PDF

ePub

Docbook

Confluence Wiki

Reveal JS Presentation

A huge amount of outputs:

https://doctoolchain.github.io/docToolchain/

@stoeps #FrOSCon14 #DocumentationWithAnyEditor39

Use ThemesYou can build your own themes

PDF

HTML

CSS

https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc

https://themes.asciidoctor.org

@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

@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)

@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

@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

@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

@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

@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

@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

@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

@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

@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:

@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:

@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

@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

@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

@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

@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

@stoeps #FrOSCon14 #DocumentationWithAnyEditor57

Gitlab Pipeline

1 Build pipeline ran successful2 Failed execution3 Download artifacts (Output formats)

@stoeps #FrOSCon14 #DocumentationWithAnyEditor58

Demo

@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

@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

top related