Re-Write source2adoc

[sebastian-sommerfeld-io]

As the maintainer of the Source2Adoc project, I am initiating a significant refactoring, transitioning our implementation from Go and Cobra to Kotlin and Spring Shell. This user story marks the beginning of this refactoring providing a clean slate to re-evaluate and enhance our approach to documentation generation.

• Kotlin with spring Shell or Go ??? Really think about this again and write an ADR
  • IntelliJ with DevContainers?
  • IntelliJ with GitHub Copilot?
  • Install IntelliJ with Ansible (configs repo)
• Event Driven Architecture
• Do not limit the Code files to a given language. Always generate Docs for all languages. Generate 1 single nav.adoc where all code files are correctly sorted.

Update: While working on this story, there again is a possibility that Go and Cobra might be the tools of choice again.

Basic Feature set

Generate documentation files for code types / languages:

• Bash
• yaml and yml
• Dockerfile (with suffixes like Dockerfile.app)
• Vagrantfile
• Makefile

Mimic the filesystem layout of the source code in the documentation to preserve the code file organization.

Tasks

• [x] New Branch "refactor-kotlin"
• [x] Clear almost everything
• [x] Prepare Dockerfile.app and Dockerfile.docs
• [x] Setup pre-commit
  • [ ] #100
  • [x] Build images locally
• [x] Update Dev Container to work with Java / Kotlin
  • [x] Install VSCode Plugins for Kotlin, Java, Maven, JUnit, GitHub Copilot
  • [x] Install Java
  • [x] Install Maven
  • [x] Install Kotlin
• [x] Refactor Antora docs to look more like the krokidile docs
  • [x] Build locally (Dockerfile.docs) with the Antora Default UI (do not use a custom UI yet)
  • [x] Review Docs
  • [x] Write "Usage" docs (remember the --source-dir and --output-dir flags and the matching docker volume mounts and workdir)
  • [x] Write "Development" docs
  • [x] #97
• [x] Setup GitHub actions workflows similar to krokidile (with semantic-release)
• [x] Review and cleanup all Issues
• [x] Enable Docker Scout Scans once a build from main occured (because so far there never was a rc-image for the docs-image)
• [x] Scan with SonarCloud
• [x] Link to GitHub Releases (which is automatically the Changelog) from somewhere on the documentation website.
• [x] #98

Ecosystem Choice and basic development

• [x] Setup a basic Spring Shell app with Kotlin
  • [x] Build locally (Dockerfile.app) and print the version or some other generic information
  • [x] Do not run the app inside the container as root
  • [x] Setup Tests with ArchUnit
• [x] Add a Go implementation for the same basic usecase and compare development, code style, feeling, build time, simplicity, ...
• [x] ADR: Kotlin + Spring Shell vs Go and Cobra
• [x] Ask Chat GPT (with this diagram): Is this really event driven / message driven? Or just decoupled? Would decoupled suffice? How to start the implementation?

Features and implementation todos

• [x] #121
• [x] https://github.com/sommerfeld-io/source2adoc/pull/86
  • [x] Write metadata into adoc files
  • [x] Write header docs into adoc files
• [ ] #99
• [x] Scan Go Dependencies for licenses (must be compatible with MIT) - see https://github.com/google/go-licenses
• [x] https://github.com/sommerfeld-io/source2adoc/issues/90
• [ ] #118
• [x] https://github.com/sommerfeld-io/source2adoc/issues/91
  • [x] https://github.com/sommerfeld-io/source2adoc/issues/102
• [ ] #117
• [x] Introduce a flag to set the target-dir of the docs files (so I can point to the antora dir) and generate the docs in the same filesystem layout as the source files
• [x] Introduce a flag to point to the dir with the source files
• [ ] #103
• [ ] #120
• [ ] #104
• [ ] #119

Possible Follow Ups

• [ ] #116
• [x] #108
• [ ] #114
• [ ] #115
• [x] Test docker images with Inspec (do not add to local docker-compose.yml, just test from pipeline)
  • [x] Run Linux Baseline against images
  • [x] #107
• [ ] #122
• [ ] #123
• [ ] #124
• [ ] #111
• [ ] #113
• [ ] #112

[sebastian-sommerfeld-io]

Still some stuff to do

[sebastian-sommerfeld-io]

Created dedicated issues for all remaining todos. This issue will be closed now. Dedicated issues allow better tracking.