Merge pull request #3233 from eseiler/infra/check_markdown

[INFRA] Check markdown files for doxygen

.github/workflows/license_check.yaml

@@ -1,22 +1,41 @@
 # SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
 # SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
 # SPDX-License-Identifier: CC0-1.0
-name: REUSE Compliance Check
+
+name: License
 
 on:
   push:
     branches:
       - 'main'
-      - 'main'
   pull_request:
+    types:
+      - unlabeled
   workflow_dispatch:
 
+concurrency:
+  group: license-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name != 'push' }}
+
+env:
+  TZ: Europe/Berlin
+
+defaults:
+  run:
+    shell: bash -Eexuo pipefail {0}
+
 jobs:
-  license_check:
-    runs-on: ubuntu-latest
+  check:
+    name: REUSE Compliance
+    runs-on: ubuntu-22.04
+    timeout-minutes: 120
+    if: github.repository_owner == 'seqan' || github.event_name == 'workflow_dispatch' || github.event.label.name == 'lint'
     steps:
-    - uses: actions/checkout@v4
-    - name: REUSE Compliance Check
-      uses: fsfe/reuse-action@v2
-      with:
-        args: --suppress-deprecation lint
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: REUSE Compliance Check
+        uses: fsfe/reuse-action@v2
+
+      - name: Check Markdown files for doxygen
+        run: ${{ github.workspace }}/test/scripts/check_markdown_doxygen.sh ${{ github.workspace }}

CHANGELOG.md

@@ -1,11 +1,11 @@
+# Changelog {#about_changelog}
+
 <!--
     SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
     SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
     SPDX-License-Identifier: CC-BY-4.0
 -->
 
-# Changelog {#about_changelog}
-
 [TOC]
 
 This changelog contains a top-level entry for each release with sections on new features, API changes and notable

CODE_OF_CONDUCT.md

@@ -1,11 +1,11 @@
+# Code of Conduct {#about_code_of_conduct}
+
 <!--
     SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
     SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
     SPDX-License-Identifier: CC-BY-4.0
 -->
 
-# Code of Conduct {#about_code_of_conduct}
-
 The SeqAn project adheres to the [Berlin Code of Conduct](https://berlincodeofconduct.org/). From the code of conduct:
 
 > A primary goal of all the conferences and user groups that refer to this Code of Conduct is to be inclusive to the largest number of contributors, with the most varied and diverse backgrounds possible. As such, we are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, ability, ethnicity, socioeconomic status and religion (or lack thereof).

CONTRIBUTING.md

@@ -1,7 +1,8 @@
+# Contributing {#about_contributing}
+
 <!-- SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
      SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
      SPDX-License-Identifier: CC-BY-4.0 -->
-# Contributing {#about_contributing}
 
 First of all, thanks for wanting to contribute to SeqAn! Community is important to us and we strive to maintain a great
 culture and atmosphere. Please have a look at our [Code of Conduct](\ref about_code_of_conduct).

README.md

@@ -1,11 +1,11 @@
+# SeqAn3 -- the modern C++ library for sequence analysis
+
 <!--
     SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
     SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
     SPDX-License-Identifier: CC-BY-4.0
 -->
 
-# SeqAn3 -- the modern C++ library for sequence analysis
-
 [![build status][1]][2]
 [![codecov][3]][4]
 [![license][5]][6]

test/scripts/check_markdown_doxygen.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2006-2024, Knut Reinert & Freie Universität Berlin
+# SPDX-FileCopyrightText: 2016-2024, Knut Reinert & MPI für molekulare Genetik
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Usage: check_markdown_doxygen.sh <SeqAn3 root directory>
+#
+# Checks that all markdown files start with a markdown header.
+# This is important for Doxygen to correctly parse the markdown files.
+
+ANY_FAIL=0
+
+do_check ()
+{
+    IS_CORRECT=$(head -n1 "$1" | grep -c "^#" || true)
+    if [[ $IS_CORRECT -eq 0 ]]; then
+        echo 'File does not start with a markdown header:' $1
+        ANY_FAIL=1
+    fi
+}
+
+if [[ $# -ne 1 ]]; then
+    echo "Usage: check_markdown_doxygen.sh <SeqAn3 root directory>"
+    exit 1
+fi
+
+SEQAN3_ROOT=$(readlink -f "$1")
+
+if [[ ! -d ${SEQAN3_ROOT} ]]; then
+    echo "The directory ${SEQAN3_ROOT} does not exist."
+    exit 1
+fi
+
+if [[ ! -f ${SEQAN3_ROOT}/include/seqan3/version.hpp ]]; then
+    echo "The directory ${SEQAN3_ROOT} does not seem to be the SeqAn3 root directory."
+    echo "Cannot find ${SEQAN3_ROOT}/include/seqan3/version.hpp."
+    exit 1
+fi
+
+for FILE in $(find "${SEQAN3_ROOT}/doc" -name "*.md" -and -not -path "${SEQAN3_ROOT}/doc/fragments/*")
+do
+    do_check $FILE
+done
+
+for FILE in $(find "${SEQAN3_ROOT}" -maxdepth 1 -name "*.md")
+do
+    do_check $FILE
+done
+
+exit $ANY_FAIL