Substitute code fragments with include shortcodes

[mowies]

Goal

Replace all code fragments occurring in the documentation with external files that are referenced using the {% include "filename" %}shortcode available in Material for MkDocs.
The new files should be in an assets folder inside the same folder as the docs file that is referencing them.

DoD

• all code fragments moved to files
• all references replaced with include shortcodes
• file are in correct assets folders

[ahmedavid]

@mowies ,Would it be possible to automate this?
for example go through docs and look for

"""yaml
bla
bla
"""

and extract this to a file.

I wrote a quick python script to extract yaml code samples.
Are there other code sample types?

[mowies]

It's definitely possible to automate this, the problem is naming of the files. They should be named in a way that is easily understandable. A few of them will probably also be re-usable in several docs pages.
I don't see an easy way to automate that part.
Any suggestions?

[ahmedavid]

Yes you are right, naming things is the hardest thing in IT. To give meaningful names one needs to be have domain knowledge. I can write a script to extract and replace short codes. Maybe somebody can join to help with naming.

[mowies]

Sure! Just start off with a PR and then somebody else can take over and give meaningful names to things :)

[ahmedavid]

Hi @mowies, I create a draft pr. Please see if general structure is ok.

[odubajDT]

Author unassigned. More info here #2633 (comment)