From 4903214c7a1a6e4b356db7e0e9601af0502fa7cd Mon Sep 17 00:00:00 2001 From: David Runge Date: Sat, 9 Dec 2023 12:16:52 +0100 Subject: [PATCH] Add contributing guideline on including external files Signed-off-by: David Runge --- CONTRIBUTING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c01e66e..bfb5e07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,27 @@ The syntax follows what is available in [MyST-parser]. --- +#### Including files + +It is advisable to [include external files](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#including-code-from-files) with data, instead of using a code block to display the data. + +--- +**NOTE**: The reason for this is, that `codespell` is used to check for common spelling mistakes and output from other programs may contain text, that will trigger it to flag it as an error. + +To work around this issue, `codespell` is configured to ignore example files, so that not entire chapter files have to be ignored. + +--- + +Use the `{literalcode}` directive to include files: + +```` + +```{literalinclude} examples/my-example.txt +:language: text +``` + +```` + #### Cross-referencing There are a few guidelines when it comes to cross-referencing, which work around oddities with [sphinx] and [MyST-parser]: