one doc

spoud · Feb 5, 2024 · 5e60a64 · 5e60a64
1 parent ed551fb
commit 5e60a64
Show file tree

Hide file tree

Showing 36 changed files with 148 additions and 130 deletions.
diff --git a/.github/workflows/asciidoctor-ghpages.yaml b/.github/workflows/asciidoctor-ghpages.yaml
@@ -0,0 +1,33 @@
+name: GitHub Pages Publish
+
+# Controls when the action will run. Triggers the workflow on push or pull request
+# events but only for the master branch
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v3
+
+      # Includes the AsciiDoctor GitHub Pages Action to convert adoc files to html and publish to gh-pages branch
+      - name: asciidoctor-ghpages
+        uses: manoelcampos/asciidoctor-ghpages-action@v2
+        with:
+          pdf_build: true
+          # asciidoctor_params: --attribute=nofooter
+          # adoc_file_ext: .ascii # default is .adoc
+          source_dir: docs/ # default is .
+          # slides_build: true
+          # pre_build:
+          # post_build:
diff --git a/docs/architecture/index.adoc b/docs/architecture/index.adoc
@@ -1,11 +1,4 @@
-// configure EN settings for asciidoc
-include::src/config.adoc[]
-
-= Kafka Cost Control
-:toc-title: Table of Contents
-
-// numbering from here on
-:numbered:
+== Architecture
 
 <<<
 // 1. Introduction and Goals

diff --git a/docs/architecture/src/01_introduction_and_goals.adoc b/docs/architecture/src/01_introduction_and_goals.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-introduction-and-goals]]
-== Introduction and Goals
+=== Introduction and Goals
 ////
 Describes the relevant requirements and the driving forces that software architects and development team must consider.
 These include
@@ -24,7 +24,7 @@ Kafka Cost Control gives organizations transparency into the costs caused by app
 * allows defining rules for platform cost distribution over organizational units or applications
 * works for most organizations, no matter if they use Confluent Cloud, Kubernetes or on-prem installations
 
-=== Requirements Overview
+==== Requirements Overview
 ////
 .Contents
 Short description of the functional requirements, driving forces, extract (or abstract)
@@ -90,7 +90,7 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum
 9. Ability to reprocess raw data in case a mistake was made. For example we see at the end of the month that an item was
 wrongly attributed to an OU. We should be able to correct this and reprocess the data.
 
-=== Quality Goals
+==== Quality Goals
 
 1. *Transferability / Extensibility*: Kafka Cost Control should be modular, so that company-specific extensions can be added. +
    A core layer should contain common base functionality.
@@ -119,7 +119,7 @@ If you as an architect do not know how the quality of your work will be judged..
 A table with quality goals and concrete scenarios, ordered by priorities
 ////
 
-=== Stakeholders
+==== Stakeholders
 
 ////
 .Contents

diff --git a/docs/architecture/src/02_architecture_constraints.adoc b/docs/architecture/src/02_architecture_constraints.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-architecture-constraints]]
-== Architecture Constraints
+=== Architecture Constraints
 
 
 ////

diff --git a/docs/architecture/src/03_system_scope_and_context.adoc b/docs/architecture/src/03_system_scope_and_context.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-system-scope-and-context]]
-== System Scope and Context
+=== System Scope and Context
 
 Kafka Cost Control is a standalone application that needs to integrate into an existing IT landscape.
 

diff --git a/docs/architecture/src/04_solution_strategy.adoc b/docs/architecture/src/04_solution_strategy.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-solution-strategy]]
-== Solution Strategy
+=== Solution Strategy
 ////
 .Contents
 A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes
@@ -28,7 +28,7 @@ See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentat
 
 ////
 
-=== Used Technologies
+==== Used Technologies
 
 
 |===

diff --git a/docs/architecture/src/05_building_block_view.adoc b/docs/architecture/src/05_building_block_view.adoc
@@ -3,7 +3,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-building-block-view]]
 
 
-== Building Block View
+=== Building Block View
 
 ////
 .Content
@@ -40,7 +40,7 @@ See https://docs.arc42.org/section-5/[Building Block View] in the arc42 document
 ////
 
 
-=== Whitebox Overall System
+==== Whitebox Overall System
 
 ////
 Here you describe the decomposition of the overall system using the following white box template. It contains
@@ -149,7 +149,7 @@ Please prefer relevance over completeness. Specify important, surprising, risky,
 Leave out normal, simple, boring or standardized parts of your system
 ////
 
-=== PricingRules
+==== PricingRules
 
 [plantuml, target=pricingrules, format=svg]
 ....
@@ -170,7 +170,7 @@ queue pricing_rules <<Topic>>
 
 
 
-=== ContextProvider
+==== ContextProvider
 
 
 [plantuml, target=contextprovider, format=svg]
@@ -192,7 +192,7 @@ component Kafka {
 ....
 
 
-==== Context format
+===== Context format
 * metrics are defined in the core
 * a metric belongs to at least one of the dimensions
 ** topic
@@ -258,7 +258,7 @@ If naming conventions are very clear they could also be provided as a file / con
 INFO::
 Context objects will be started as AVRO messages. We use JSON as a representation here for simplicity.
 
-==== Context Lookup
+===== Context Lookup
 
 State stores in Kafka Streams will be used to construct lookup tables for the context.
 

diff --git a/docs/architecture/src/06_runtime_view.adoc b/docs/architecture/src/06_runtime_view.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-runtime-view]]
-== Runtime View
+=== Runtime View
 
 ////
 .Contents
@@ -35,7 +35,7 @@ See https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation.
 
 ////
 
-=== Metrics Ingestion from Confluent Cloud
+==== Metrics Ingestion from Confluent Cloud
 
 Process to gather and aggregate metrics from Confluent Cloud.
 
@@ -75,7 +75,7 @@ Telegraf -right-> "raw-metrics": produce
 @enduml
 ....
 
-=== Metrics using Kafka Admin API
+==== Metrics using Kafka Admin API
 
 Some information can be gathered from the Kafka Admin API. We will develop a simple application that connect to the Kafka Admin API and expose metrics as prometheus endpoint. We can then reuse Telegraf to publish those metrics to kafka.
 
@@ -96,12 +96,12 @@ Telegraf -right-> "raw-metrics": produce
 @enduml
 ....
 
-=== Other sources of metrics
+==== Other sources of metrics
 
 Anyone can publish to the raw metrics topic. The metrics should follow the telegraf format.
 Recommendation: use one topic per source of metrics. The MetricEnricher application will anyway consume multiple raw metric topics.
 
-=== Metrics Enrichment
+==== Metrics Enrichment
 
 [plantuml,target=runtime-enrich,format=svg]
 ....
@@ -133,18 +133,18 @@ MetricsProcessor -down-> "aggregated-metrics" : produce
 @enduml
 ....
 
-1. Metrics are consumed from all the raw data topics.
-1. Metrics are aggregated by the MetricsProcessor.
+. Metrics are consumed from all the raw data topics.
+. Metrics are aggregated by the MetricsProcessor.
 Here we:
  * aggregate by hours
  * attach context
  * attach pricing rule
-1. The aggregates are stored in the `aggregated-metrics` topic.
-1. The aggregated metrics are stored into the query database.
+. The aggregates are stored in the `aggregated-metrics` topic.
+. The aggregated metrics are stored into the query database.
 
 The storage procedure into the query database must be idempotent in order to reprocess the enrichment in case of reprocessing.
 
-==== Enrichment for topics
+===== Enrichment for topics
 
 .metric with topic name from confluent cloud
 [source,json]
@@ -165,7 +165,7 @@ The storage procedure into the query database must be idempotent in order to rep
 }
 ----
 
-==== Enrichment for principals
+===== Enrichment for principals
 
 .metric with principal id from confluent cloud
 [source,json]
@@ -187,7 +187,7 @@ The storage procedure into the query database must be idempotent in order to rep
 }
 ----
 
-=== Metrics Grouping
+==== Metrics Grouping
 
 - confluent_kafka_server_request_bytes by kafka_id (Cluster) and principal_id (User) for the type Produce as sum stored in produced_bytes
 - confluent_kafka_server_response_bytes by kafka_id (Cluster) and principal_id (User) for the type Fetch as sum stored in fetched_bytes

diff --git a/docs/architecture/src/07_deployment_view.adoc b/docs/architecture/src/07_deployment_view.adoc
@@ -3,7 +3,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-deployment-view]]
 
 
-== Deployment View
+=== Deployment View
 
 [plantuml,target=deployment-view,format=svg]
 ....
@@ -62,7 +62,7 @@ actor "User"
 ....
 
 
-== Installation
+=== Installation
 
 Please follow the installation instructions from the link:../installation/[installation folder].
 
diff --git a/docs/architecture/src/08_concepts.adoc b/docs/architecture/src/08_concepts.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-concepts]]
-== Cross-cutting Concepts
+=== Cross-cutting Concepts
 
 
 ////
@@ -18,10 +18,10 @@ They can include many different topics, such as
 
 
 .Motivation
-Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture. 
+Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture.
 Thus, they are an important contribution to achieve inner qualities of your system.
 
-Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety. 
+Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.
 
 
 .Form
@@ -55,18 +55,18 @@ See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation.
 ////
 
 
-=== _<Concept 1>_
+==== _<Concept 1>_
 
 _<explanation>_
 
 
 
-=== _<Concept 2>_
+==== _<Concept 2>_
 
 _<explanation>_
 
 ...
 
-=== _<Concept n>_
+==== _<Concept n>_
 
 _<explanation>_
diff --git a/docs/architecture/src/09_architecture_decisions.adoc b/docs/architecture/src/09_architecture_decisions.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-design-decisions]]
-== Architecture Decisions
+=== Architecture Decisions
 
 
 ////
@@ -13,7 +13,7 @@ Please use your judgement to decide whether an architectural decision should be
 here in this central section or whether you better document it locally
 (e.g. within the white box template of one building block).
 
-Avoid redundancy. 
+Avoid redundancy.
 Refer to section 4, where you already captured the most important decisions of your architecture.
 
 .Motivation

diff --git a/docs/architecture/src/10_quality_requirements.adoc b/docs/architecture/src/10_quality_requirements.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-quality-scenarios]]
-== Quality Requirements
+=== Quality Requirements
 
 
 ////
@@ -24,7 +24,7 @@ See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 docume
 
 ////
 
-=== Quality Tree
+==== Quality Tree
 
 ////
 .Content
@@ -44,7 +44,7 @@ In any case the tree should include links to the scenarios of the following sect
 
 ////
 
-=== Quality Scenarios
+==== Quality Scenarios
 
 ////
 .Contents

diff --git a/docs/architecture/src/11_technical_risks.adoc b/docs/architecture/src/11_technical_risks.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-technical-risks]]
-== Risks and Technical Debts
+=== Risks and Technical Debts
 
  * Difficulty to get context data
     ** Will the customer be willing to make the effort to provide the necessary data?

diff --git a/docs/architecture/src/12_glossary.adoc b/docs/architecture/src/12_glossary.adoc
@@ -1,7 +1,7 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-glossary]]
-== Glossary
+=== Glossary
 
 
 

diff --git a/docs/architecture/src/config.adoc b/docs/architecture/src/config.adoc
diff --git a/docs/manual/src/config.adoc → docs/config.adoc b/docs/manual/src/config.adoc → docs/config.adoc
diff --git a/...mages/01_2_iso-25010-topics-EN.drawio.png → ...mages/01_2_iso-25010-topics-EN.drawio.png b/...mages/01_2_iso-25010-topics-EN.drawio.png → ...mages/01_2_iso-25010-topics-EN.drawio.png
diff --git a/...itecture/images/05_building_blocks-EN.png → docs/images/05_building_blocks-EN.png b/...itecture/images/05_building_blocks-EN.png → docs/images/05_building_blocks-EN.png
diff --git a/...08-Crosscutting-Concepts-Structure-EN.png → ...08-Crosscutting-Concepts-Structure-EN.png b/...08-Crosscutting-Concepts-Structure-EN.png → ...08-Crosscutting-Concepts-Structure-EN.png
diff --git a/docs/architecture/images/arc42-logo.png → docs/images/arc42-logo.png b/docs/architecture/images/arc42-logo.png → docs/images/arc42-logo.png