New docs: include source files

[m-vdb]

⬆️ Relates to RasaHQ/growth#1436

We need to support the previous .. literalinclude:: directives. We can use remark-sources and manually replace (it cannot be done by the rst-to-markdown converter because sphinx loads the source file long before it's handed to the converter).

💡 We are dropping support for "parts" of a file (for instance see :start-after: or :pyobject: options). This will require some documentation work.

Implementation proposal

What I think we can do (similarly to what we did with variables.json):

1. keep the links as is in the mdx files
2. write a custom pre-processor that copies all "source" files inside the docs/sources folder (for instance)
3. write a custom remark plugin that looks for these files inside the docs/sources folder (or the original path). We could fork remark-sources and do that.

That way it would work both in dev and in production (where there are multiple versions). The key is to keep things under the docs folder.

[tmbo]

I think we can reduce this to the minimum and really only include complete files. In most locations, this should be fine (or alternatively even add a simpler example to the docs). I'd really only go with complete includes for now and rather rework the docs to avoid using line or object based includes (e.g. most of them are in the events section, which doesn't make sense anyways - since users are using events from rasa-sdk and not from rasa open source)

[m-vdb]

yes, fine by me. @erohmensing do you think that what @tmbo is easily doable? We might need your input to rework the content :)

[erohmensing]

Sure, we can probably handle that. In fact it might help us make our code a little cleaner, and will make sure that the user always has the necessary imports to use any code referenced.

Looks like the Forms and Reminders and External Events page will need a rework to manage referencing the content, and the Events page should get a rework for other reasons (for right now it might just make sense to take these includes out and deal with the rest of that page later)

Other than that, would be helpful for the Custom Connectors page if RestInput got its own module instead of being part of channels.py (which I think would make sense in any case, as it's not intuitive to find in the codebase)

If that sounds good I'm happy to take on the content side of these changes -- if you assign me to a PR you make to do the backend changes for the existing includes, I can update these pages on there 👍

[m-vdb]

great, thanks @erohmensing !