Enable code includes, like the literalinclude directive, with prompts

[mgielda]

Firstly, thanks for an awesome package. We're using this in the RISC-V Getting Started Guide (https://risc-v-getting-started-guide.readthedocs.io/en/latest/) and it's great.

I was curious how you would go about a problem that we have. This could be an interesting use case if we find a solution.

Namely there are two things we want to happen at the same time:

1. we'd like our code snippets to be included from real files that can also be executed, preferably using a CI system:

https://github.com/riscv/risc-v-getting-started-guide/blob/master/source/getting-zephyr.rst

This would let our guide be tested at all times, without the risk of people finding stale content.

2. for GDB snippets, we'd like to show the GDB prompt to clearly discriminate between input and output (that's where we are using your package):

https://github.com/riscv/risc-v-getting-started-guide/blob/master/source/zephyr-hifive1.rst

Of course, 1) and 2) are somewhat mutually exclusive as things are now.
If you're including a snippet, it can't have a prompt, otherwise it won't execute properly.

But my thinking is that we could probably work around this by specifying a prompt in a similar fashion as the begin and end strings for literalinclude. So surround the part with the prompt with a comment which gives it a prompt, and the part which is an execution result could also have some convention like being surrounded with an appropriate string and also commented out.

It's complex but doable, I suppose - but I would welcome your insight, @sbrunner.

@PiotrZierhoffer will also be interested in this.

[mgielda]

I would actually have a much simpler solution for this right now. If we allow literalinclude-like functionality in the prompt directive (so taking a file argument with :start-after: and :end-before:) we could basically parse our scripts before executing in CI, and remove prompts as we see fit. So the ability to include snippets from files, without all the extra fluff, is enough for our use case, and probably a zillion times simpler to implement. What do you think @sbrunner and @PiotrZierhoffer?