Substrate io integration

[JoshOrndorff]

This draft PR prepares the recipes for integration with the substrate.io website.

In particular it (will):

• Remove google analytics (that is handled in substrate.io now)
• Remove mdbook (this repo just hosts the content, the substrate.io repo has the gatsby build)
• Move each recipe writeup it the corresponding code directory

Here an example that you can see by building the recipes branch of substrate.io repository.

[JoshOrndorff]

@jimmychu0807 One big change that I've considered for a while now, and decided to implement here is that, instead of a seperate text folder for the writeups, have each writeup live in the README.md file in the pallet (or runtime or node) that it describes.

I think that is a good change for a few reasons.

1. the writeup lives closer to the code it describes, so it is easier to know what writeup to change when code changes.
2. the recipes are more browsable just by clicking through the repo in github
3. if/when the crates are published on crates.io or substrate marketplace, they actually have a readme

A few questions for you:

1. Are you okay with this change?
2. Any drawbacks I may not have considered?
3. What should we do with the ocw writeup? Currently it is divided into several parts. Should we make it one long writeup? Or split the pallet? Or something else? I'm open to ideas on this
4. What should we do with the testing writeup? Make it a tutorial? Move it to one specific test crate? Something else?

Would love your ideas on this in general.

[jimmychu0807]

I think your #3 and #4 are my immediate concerns. It is not necessarily a 1-to-1 relationship between recipes and pallets. One recipe may teach a concept that is demonstrated in a few pallets. And one pallet might teach multiple concepts and be mentioned in multiple writeups.

If we do go for your proposed change, which I translate to enforcing a 1-to-1 relationship between pallet and writeup, this likely limit the structure of our recipe in the long run. At some point, maybe we want to teach a concept that has no pallet at all, just code snippet.

I prefer the flexibility of having code on one side, and we can freely build up the structure (section / subsection etc) of the recipe on the other side. My take.

[jimmychu0807]

I think it is okay to have readme.md in the pallet. But just that I prefer not to have the recipe to be built up solely from pallets readme.md.

Can we do it this way, say we still have the text directory, building up our own recipe structure. When appropriate, we have a text/ocw/ocw-storage.md that is a symlink to a pallet readme.md. In that case, the content in the recipe will be extracted from the pallet readme.md. This will just need Matt build an additional logic of this parsing.

Now we can the advantages of both side.

[JoshOrndorff]

your proposed change, which I translate to enforcing a 1-to-1 relationship between pallet and writeup

Yeah, that's a good concise way to explain the change I'm proposing. :+1:

maybe we want to teach a concept that has no pallet at all, just code snippet.

That's how the recipes started out. The problem is there is no CI for code snippets, and stuff goes stale without anyone noticing.

You've raised some good points Jimmy. I guess I should admit that I've struggled to decide whether recipes should be based around particular concepts (like weights, ocw, instantiable pallets, fixed-point) or examples which may demonstrate multiple concepts (like basic-token, hybrid-consensus, compounding-interest). @danforbes I believe you were advocating it should focus around examples. Do you want to make that point here?

[danforbes]

I guess based on those two choices I would say I envision Recipes of being more about specific concepts than multiple concepts that inform an entire use case. I think Recipes are kind of like a collection of answers to Stack Overflow questions that we anticipate will be answered. Tutorials should be the place to tie together multiple concepts into a comprehensive user-facing use case, I think.