sdl-painter Dokümantasyon

Tekrar merhaba sevgili takipçilerim. Bir önceki yazımda, sdl-painter kütüphaneme ilişkin ilk fazına yönelik paylaşımı yapmıştım.

sdl-painter Proje Altyapısı (faz-0)

Önceki yazılımlarımda da bahsettiğim üzere, bu kütüphaneye yönelik kod dokümantasyonunu da olabildiğince LLM’leri de kullanarak oluşturmaya gayret ediyorum. Repo içerisinde /doc ve /adr dizinleri içerisinde destekleyici dokümanlar mevcut. Ayrıca, doxygen ile kod içi doküman da oluşturulmakta. Sizler için de faydalı olması adına, hem gitlab hem de github için bu sayfalar otomatik olarak oluşturuluyor. İlgili adımları inceleyerek, benzer akışları sizler de oluşturabilirsiniz.

Aşağıda, pipeline ile otomatik olarak oluşturulan dokümanları görebilirsiniz:

[Github] SDLPainter — Dokümantasyon

[Gitlab] SDLPainter — Dokümantasyon

Gitlab kısmında akış görselleştirmelerinde ufak bir durum var ama onu da gidereceğim.

Github için doküman oluşturmaya yönelik CI/CD adımları:

  docs:
    name: docs
    runs-on: ubuntu-latest
    needs: [quality-clang-format, quality-clang-tidy]
    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Install doxygen (resmi binary — Mermaid native desteği için)
        run: |
          sudo apt-get update -qq && sudo apt-get install -y graphviz jq
          asset_url=$(curl -sL https://api.github.com/repos/doxygen/doxygen/releases/latest \
            | jq -r '.assets[] | select(.name | endswith("linux.bin.tar.gz")) | .browser_download_url')
          if [ -z "$asset_url" ]; then
            echo "Doxygen linux.bin.tar.gz asset'i bulunamadı" >&2
            exit 1
          fi
          curl -sL "$asset_url" -o /tmp/doxygen.tar.gz
          mkdir -p /tmp/doxygen-install
          tar -xzf /tmp/doxygen.tar.gz -C /tmp/doxygen-install --strip-components=1
          echo "/tmp/doxygen-install/bin" >> "$GITHUB_PATH"
      - name: doxygen sürüm kontrolü
        run: doxygen --version
      - name: Generate docs
        run: |
          mkdir -p public
          AWESOME="third_party/doxygen-awesome-css/doxygen-awesome.css"
          [ -f "$AWESOME" ] || AWESOME=""
          cat > _ci_doxyfile <<EOF
          PROJECT_NAME           = "SDLPainter"
          PROJECT_NUMBER         = "$(grep 'project(SDLPainter VERSION' CMakeLists.txt | grep -oP '\d+\.\d+\.\d+')"
          PROJECT_BRIEF          = "QPainter benzeri SDL3 + OpenGL/Vulkan 2D çizim kütüphanesi"
          OUTPUT_DIRECTORY       = public
          HTML_OUTPUT            = .
          INPUT                  = include/sdl_painter doc
          FILE_PATTERNS          = *.h *.md
          RECURSIVE              = YES
          USE_MDFILE_AS_MAINPAGE = doc/README.md
          EXCLUDE_PATTERNS       = */src/* */tests/* */examples/* */third_party/*
          EXTRACT_ALL            = NO
          EXTRACT_PRIVATE        = NO
          EXTRACT_STATIC         = YES
          HIDE_UNDOC_MEMBERS     = YES
          HIDE_UNDOC_CLASSES     = YES
          GENERATE_HTML          = YES
          GENERATE_LATEX         = NO
          HTML_EXTRA_STYLESHEET  = $AWESOME
          HTML_COLORSTYLE        = LIGHT
          HTML_TIMESTAMP         = NO
          HAVE_DOT               = YES
          DOT_IMAGE_FORMAT       = svg
          INTERACTIVE_SVG        = YES
          CLASS_GRAPH            = YES
          COLLABORATION_GRAPH    = NO
          CALL_GRAPH             = NO
          QUIET                  = YES
          WARNINGS               = YES
          WARN_IF_UNDOCUMENTED   = YES
          WARN_NO_PARAMDOC       = YES
          OUTPUT_LANGUAGE        = Turkish
          SEARCHENGINE           = YES
          EOF
          doxygen _ci_doxyfile
      - uses: actions/upload-pages-artifact@v3
        with:
          path: public
      - id: deployment
        uses: actions/deploy-pages@v4

docs:

name: docs

runs-on: ubuntu-latest

needs: [quality-clang-format, quality-clang-tidy]

if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)

permissions:

contents: read

pages: write

id-token: write

environment:

name: github-pages

url: ${{ steps.deployment.outputs.page_url }}

steps:

- uses: actions/checkout@v4

with:

submodules: recursive

- name: Install doxygen (resmi binary — Mermaid native desteği için)

run: |

sudo apt-get update -qq && sudo apt-get install -y graphviz jq

asset_url=$(curl -sL https://api.github.com/repos/doxygen/doxygen/releases/latest \

| jq -r '.assets[] | select(.name | endswith("linux.bin.tar.gz")) | .browser_download_url')

if [ -z "$asset_url" ]; then

echo "Doxygen linux.bin.tar.gz asset'i bulunamadı" >&2

exit 1

curl -sL "$asset_url" -o /tmp/doxygen.tar.gz

mkdir -p /tmp/doxygen-install

tar -xzf /tmp/doxygen.tar.gz -C /tmp/doxygen-install --strip-components=1

echo "/tmp/doxygen-install/bin" >> "$GITHUB_PATH"

- name: doxygen sürüm kontrolü

run: doxygen --version

- name: Generate docs

run: |

mkdir -p public

AWESOME="third_party/doxygen-awesome-css/doxygen-awesome.css"

[ -f "$AWESOME" ] || AWESOME=""

cat > _ci_doxyfile <<EOF

PROJECT_NAME = "SDLPainter"

PROJECT_NUMBER = "$(grep 'project(SDLPainter VERSION' CMakeLists.txt | grep -oP '\d+\.\d+\.\d+')"

PROJECT_BRIEF = "QPainter benzeri SDL3 + OpenGL/Vulkan 2D çizim kütüphanesi"

OUTPUT_DIRECTORY = public

HTML_OUTPUT = .

INPUT = include/sdl_painter doc

FILE_PATTERNS = *.h *.md

RECURSIVE = YES

USE_MDFILE_AS_MAINPAGE = doc/README.md

EXCLUDE_PATTERNS = */src/* */tests/* */examples/* */third_party/*

EXTRACT_ALL = NO

EXTRACT_PRIVATE = NO

EXTRACT_STATIC = YES

HIDE_UNDOC_MEMBERS = YES

HIDE_UNDOC_CLASSES = YES

GENERATE_HTML = YES

GENERATE_LATEX = NO

HTML_EXTRA_STYLESHEET = $AWESOME

HTML_COLORSTYLE = LIGHT

HTML_TIMESTAMP = NO

HAVE_DOT = YES

DOT_IMAGE_FORMAT = svg

INTERACTIVE_SVG = YES

CLASS_GRAPH = YES

COLLABORATION_GRAPH = NO

CALL_GRAPH = NO

QUIET = YES

WARNINGS = YES

WARN_IF_UNDOCUMENTED = YES

WARN_NO_PARAMDOC = YES

OUTPUT_LANGUAGE = Turkish

SEARCHENGINE = YES

EOF

doxygen _ci_doxyfile

- uses: actions/upload-pages-artifact@v3

with:

path: public

- id: deployment

uses: actions/deploy-pages@v4

Gitlab için doküman oluşturmaya yönelik CI/CD adımları:

# --- Docs Stage ---

# GitLab Pages: job adı 'pages' olmalı, artifact 'public/' altına gitmeli.
# Conan/CMake gerektirmez — doxygen doğrudan include/ ve doc/ üzerinde çalışır.
pages:
  stage: docs
  image: ubuntu:24.04
  needs: []
  before_script:
    - apt-get update -qq && apt-get install -y doxygen graphviz
  script:
    - mkdir -p public
    - |
      AWESOME="third_party/doxygen-awesome-css/doxygen-awesome.css"
      [ -f "$AWESOME" ] || AWESOME=""
      cat > _ci_doxyfile <<EOF
      PROJECT_NAME           = "SDLPainter"
      PROJECT_NUMBER         = "$(grep 'project(SDLPainter VERSION' CMakeLists.txt | grep -oP '\d+\.\d+\.\d+')"
      PROJECT_BRIEF          = "QPainter benzeri SDL3 + OpenGL/Vulkan 2D çizim kütüphanesi"
      OUTPUT_DIRECTORY       = public
      HTML_OUTPUT            = .
      INPUT                  = include/sdl_painter doc
      FILE_PATTERNS          = *.h *.md
      RECURSIVE              = YES
      USE_MDFILE_AS_MAINPAGE = doc/README.md
      EXCLUDE_PATTERNS       = */src/* */tests/* */examples/* */third_party/*
      EXTRACT_ALL            = NO
      EXTRACT_PRIVATE        = NO
      EXTRACT_STATIC         = YES
      HIDE_UNDOC_MEMBERS     = YES
      HIDE_UNDOC_CLASSES     = YES
      GENERATE_HTML          = YES
      GENERATE_LATEX         = NO
      HTML_EXTRA_STYLESHEET  = $AWESOME
      HTML_COLORSTYLE        = LIGHT
      HTML_TIMESTAMP         = NO
      HAVE_DOT               = YES
      DOT_IMAGE_FORMAT       = svg
      INTERACTIVE_SVG        = YES
      CLASS_GRAPH            = YES
      COLLABORATION_GRAPH    = NO
      CALL_GRAPH             = NO
      QUIET                  = YES
      WARNINGS               = YES
      WARN_IF_UNDOCUMENTED   = YES
      WARN_NO_PARAMDOC       = YES
      OUTPUT_LANGUAGE        = Turkish
      SEARCHENGINE           = YES
      EOF
    - doxygen _ci_doxyfile
  artifacts:
    paths:
      - public/
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# --- Docs Stage ---

# GitLab Pages: job adı 'pages' olmalı, artifact 'public/' altına gitmeli.

# Conan/CMake gerektirmez — doxygen doğrudan include/ ve doc/ üzerinde çalışır.

pages:

stage: docs

image: ubuntu:24.04

needs: []

before_script:

- apt-get update -qq && apt-get install -y doxygen graphviz

script:

- mkdir -p public

- |