CI: Require at least one code block separator for example files in th…

…e Style Checks workflow (#2810)

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

@@ -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

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.