Asciidoc on Micha Kops' Tech Notes

Modeling AWS Structures with PlantUML and AsciiDoc

Tue, 08 Nov 2022 00:00:00 +0100

The AWS shapes are included in the PlantUML stdlib .. simply include them as shown here:

example.puml

@startuml
!include <awslib/AWSCommon>
!include <awslib/Analytics/ManagedStreamingforKafka>
!include <awslib/Database/RDS>
!include <awslib/General/Users>
!include <awslib/General/InternetGateway>

!include <kubernetes/k8s-sprites-labeled-25pct>

skinparam linetype ortho

title "AWS Context Diagram"


package "EKS Kubernetes Cluster" as eks_cluster {
    component "<$pod>\napp1" as pod1
    component "<$pod>\napp2" as pod2
}

ManagedStreamingforKafka(kafka_pod, "Amazon MSK", "Apache Kafka")

RDS(pg_rds, "PostgreSQL", "Sample Schema")


Users(users, "AppUsers","editors, admins")

InternetGateway(igw1, "Customer Gateway", "Customer access to internal services")

users -> igw1
igw1 --> pod1
igw1 --> pod2
pod1 --> pg_rds
pod1 --> kafka_pod
pod2 --> pg_rds
pod2 --> kafka_pod

@enduml

C4 Modeling with PlantUML and AsciiDoc

Tue, 01 Nov 2022 00:00:00 +0100

C4 models allow us to visualize software architecture by decomposition in containers and components.

Viewpoints are organized in hierarchical levels:

Context Diagrams (Level 1)
Container Diagrams (Level 2)
Component Diagrams (Level 3)
Code Diagrams (Level 4)

C4-PlantUML offers a variety of macros and stereotypes that make modeling fun.

An example in PlantUML:

sample.puml

@startuml
!include <c4/C4_Context.puml>
!include <c4/C4_Container.puml>

left to right direction

Person(user, "User")

System_Ext(auth, "AuthService", "Provides authentication and authorization via OIDC")

System_Boundary(zone1, "Some system boundary") {


    System(lb, "Load Balancer")

    System_Boundary(az, "App Cluster") {
        System(app, "App Servers") {
            Container(app1, "App1", "Docker", "Does stuff")
            Container(app2, "App1", "Docker", "Does stuff")

            ContainerDb(dbSess, "Session DB", "Redis")
            ContainerDb(db1, "RBMS 1", "AWS RDS Postgres")
            ContainerDb(db2, "RBMS 2", "AWS RDS Postgres")

            ' both app servers sync sessions via redis
            Rel(app1, dbSess, "Uses", "Sync Session")
            Rel(app2, dbSess, "Uses", "Sync Session")

            ' both app servers persist data in RDBMS
            Rel(app1, db1, "Uses", "Persist/query relational data")
            Rel(app2, db2, "Uses", "Persist/query relational data")
        }
    }
}

Rel(user, lb, "call")
Rel(lb, app1, "delegate")
Rel(lb, app2, "delegate")
Rel(app1, auth, "Verify", "User auth")
Rel(app2, auth, "Verify", "User auth")

SHOW_FLOATING_LEGEND()

@enduml

AsciiDoc Snippets

Fri, 10 May 2019 00:00:00 +0200

AsciiDoc Syntax and Features

Using AsciiMath

Include stem into document header

:stem:

Then use inline, e.g.:

stem:[sqrt(4) = 2]

or as block

[stem]
++++
sum_(i=1)^n i^3=((n(n+1))/2)^2
++++

AsciiMath Syntax

Collapsible Blocks/Sections

.Click to show the content
[%collapsible]
====
Long content here...
====

Source: Asciidoctor Docs

Tools and Ecosystem

Docker / Podman Container

Including stuff like:

Asciidoctor
Asciidoctor Diagram with ERD and Graphviz integration (supports plantuml and graphiz diagrams)
Asciidoctor PDF
Asciidoctor EPUB3
Asciidoctor FB2
Asciidoctor Mathematical
Asciidoctor reveal.js
AsciiMath
Source highlighting using Rouge, CodeRay or Pygments
Asciidoctor Confluence
Asciidoctor Bibtex
Asciidoctor Kroki
Asciidoctor Reducer

Software Architecture Exploration and Validation with jqAssistant, Neo4j and Cypher

Sun, 31 Dec 2017 00:00:00 +0100

I have written about other software system analyzing and validation tools before but today I would like to introduce a new tool named jqAssistant that supports software architects, developers and analysts in a variety of tasks like analyzing given structures, validating architectural or quality constraints and generating reports.

Therefore jqAssistant analyzes given projects or artifacts and stores the gathered information – that is enriched by a variety of existing plugin-ins – in a Neo4j graph database.

Documenting RESTful Webservices in Swagger, AsciiDoc and Plain Text with Maven and the JAX-RS Analyzer

Tue, 16 Jun 2015 00:00:00 +0200

A variety of different tools exists to help us analyze RESTful web-services and create documentations for their APIs in different formats.

In the following tutorial I’d like to demonstrate how to document an existing JAX-RS web-service in multiple formats like Swagger, AsciiDoc or Plain Text using Maven, the JAX-RS Analyzer and the JAX-RS Analyzer Maven Plugin.

The JAX-RS Analyzer gathers its information not only by reflection like most other tools but also by bytecode analysis and therefore does not require us to add special annotations for documentation to our code.

GitHub Snippets

Mon, 01 Mar 2010 00:00:00 +0100

GitHub Actions

Step to check variables and redistribute as env

The following step does ..

check of given variables are set, if not, exit with an error that is visible in the action’s log
provide the given input as environment variable in GITHUB_ENV

- name: configuration
      env:
        VAR1: ${{ needs.configure.outputs.something }}
        VAR2: ${{ vars.SOMETHING_OTHER }}/
        VAR3: "something_other_other"
      run: |
        for var in VAR1 VAR2 VAR3; do [ -n "${!var}" ] || { echo "$var is missing"; exit 1; }; echo "$var=${!var}" >> "$GITHUB_ENV"; done

GitLab Snippets

Mon, 01 Mar 2010 00:00:00 +0100

Generate AsciiDoc Documentation and Publish it with GitLab Pages

We setup a repository and add a directory named docs there .. this is the home of our AsciiDoc files.

We’re using asciidoctor/docker-asciidoctor as Docker image for tool provisioning

This is the .gitlab-ci.yml, we’re running the stage only when something in the docs directory has changed.

stages:
  - "Build docs"

# The name of the job activates the GitLab pages publication
pages:
  image: asciidoctor/docker-asciidoctor
  stage: "Build docs"
  tags:
    - build
  script:
    - sh ./gen_docs.sh
    - mv output public
  only:
    refs:
      - master
    changes:
      - /docs/*
  artifacts:
    paths:
      - public
    expose_as: 'Documentation Archive'