Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Python guide: include code examples using Jekyll #519

Open
gkunz opened this issue Jun 1, 2024 · 2 comments · May be fixed by #528
Open

Python guide: include code examples using Jekyll #519

gkunz opened this issue Jun 1, 2024 · 2 comments · May be fixed by #528

Comments

@gkunz
Copy link
Contributor

gkunz commented Jun 1, 2024

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
Copy link
Contributor

myteron commented Jun 3, 2024

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
Copy link
Contributor Author

gkunz commented Jun 3, 2024

tommcd added a commit to tommcd/wg-best-practices-os-developers that referenced this issue Jun 5, 2024
@tommcd tommcd linked a pull request Jun 5, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants