Python guide: include code examples using Jekyll

[gkunz]

One objective of the Python guide is to provide executable code examples in separate Python scripts. At the same time, the code examples should also be shown in listings in the guide.

Problem: Markdown itself does not allow to include other files, i.e., such as the code examples.

Proposal: To avoid duplicating the code of the scripts in the markdown files, we can use Jekyll's include_relate primitive [1] to include the scripts in the rendered guide.

Specifically, this pattern seems to work:

```python
{% include_relative compliant01.py %}
```

[1] https://jekyllrb.com/docs/includes/#including-files-relative-to-another-file

cc @myteron @tommcd

[myteron]

Gut feeling tells me that Jekyll appears to me a little to flexible with a potential for injection via variables. Haven't tried.
Editing requires to compile and run a web-server. Was somewhat hoping for a more simplistic solution.

[gkunz]

Jekyll is run under the hood by GitHub when rendering the current guides.

I run a test using my fork:

• Code: https://github.com/gkunz/wg-best-practices-os-developers/blob/0afa4264397698051ee0be84f219a34cf73c8f46/docs/Secure-Coding-Guide-for-Python/CWE-664/CWE-134/README.md?plain=1#L19

• Resulting render (notice that the first example appears twice: https://gkunz.github.io/wg-best-practices-os-developers/docs/Secure-Coding-Guide-for-Python/CWE-664/CWE-134/

[s19110]

Should the separate Python scripts necessarily be separate files, or could they be executable code chunks embedded within the guide itself?

One of the options I have found for having executable Python code is using RMarkdown: https://rmarkdown.rstudio.com/
While it mainly uses R, it can also support Python: https://medium.com/data-and-beyond/how-to-seamlessly-integrate-python-into-r-rmarkdown-codes-2fe09cfdd0ee
Although, from what I saw when browsing GitHub, there are no previews for .rmd files, unfortunately.

Alternatively, could Jupyter Notebook be a good alternative? This way we would have both the guide and the code examples in a singular file, which would prevent code duplication, while also being able to independently run the code examples.

[tommcd]

Should the separate Python scripts necessarily be separate files, or could they be executable code chunks embedded within the guide itself?

One of the options I have found for having executable Python code is using RMarkdown: https://rmarkdown.rstudio.com/ While it mainly uses R, it can also support Python: https://medium.com/data-and-beyond/how-to-seamlessly-integrate-python-into-r-rmarkdown-codes-2fe09cfdd0ee Although, from what I saw when browsing GitHub, there are no previews for .rmd files, unfortunately.

Alternatively, could Jupyter Notebook be a good alternative? This way we would have both the guide and the code examples in a singular file, which would prevent code duplication, while also being able to independently run the code examples.

+1 for Jupyter Notebooks