From 29610d7f19e45bc432838d9ae95313d3143ab5ac Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Sat, 18 Nov 2023 18:00:13 +0800
Subject: [PATCH] CI: Require at least one code block separator for example
 files in the Style Checks workflow (#2810)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>
Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 .github/workflows/style_checks.yaml | 11 +++++++++++
 doc/contributing.md                 |  7 +++++++
 2 files changed, 18 insertions(+)

diff --git a/.github/workflows/style_checks.yaml b/.github/workflows/style_checks.yaml
index a286b7c85b5..9b58341e10e 100644
--- a/.github/workflows/style_checks.yaml
+++ b/.github/workflows/style_checks.yaml
@@ -49,3 +49,14 @@ jobs:
           find . -type f -not -path '*/\.git/*' -exec grep -Iq . {} \; -exec dos2unix --quiet {} \;
           find . -type f -not -path '*/\.git/*' -exec grep -Iq . {} \; -exec chmod 644 {} \;
           if [[ $(git ls-files -m) ]]; then git --no-pager diff HEAD; exit 1; fi
+
+      - name: Ensure example scripts have at least one code block separator
+        run: |
+          grep --files-without-match '# %%' $(find 'examples' -name '*.py') > output.txt
+          nfiles=$(wc --lines output.txt | awk '{print $1}')
+          if [[ $nfiles > 0 ]]; then
+            echo "Code block separator '# %%' is required in following example files:"
+            cat output.txt
+            rm output.txt
+            exit $nfiles
+          fi
diff --git a/doc/contributing.md b/doc/contributing.md
index c44e80d5ae5..4ccdfbd2416 100644
--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -499,6 +499,13 @@ words bridged only by consonants, such as `distcalc`, and `crossprofile`. This
 convention is not applied by the code checking tools, but the PyGMT maintainers
 will comment on any pull requests as needed.
 
+When working on a tutorial or a gallery plot, it is good practice to use code
+block separators to split a long script into multiple blocks. The separators also
+make it possible to run the script like a Jupyter notebook in some modern text
+editors or IDEs. We consistently use `# %%` as code block separators (please
+refer to [issue #2660](https://github.com/GenericMappingTools/pygmt/issues/2660)
+for the discussions) and require at least one separator in all example files.
+
 We also use [ruff](https://docs.astral.sh/ruff) and
 [pylint](https://pylint.pycqa.org/) to check the quality of the code and quickly catch
 common errors.