examples overhaul

• We should also add a readme to the tortoise integration
• We should add a brief top-level readme to the examples directory, explaining the separation between agent-core and network, how to navigate/use it

To improve maintainability (no redundancy, single source for documentation/definitions) I would suggest the following:

• Only include example logic specific descriptions and explanations in the example's readme
• put all "general" documentation into (a) separate file(s)
• Link to any "general" description/documentation that is needed for an example (e.g., address, seed, bureau etc. basically everything that also should have a proper docstring)
• If we switch from markdown to asciidocs we can even do includes to compile standalone files without linking and without copy-and-paste redundancies
• eventually we should maintain valid, useful and up-to-date docstrings, which should be used to populate any base documentation (e.g., in example readmes or for general api documentation) and additional documentation would only be needed for concepts, architecture descriptions, examples, etc.

Good points @Dacksus. Definitely agree with both of the first tasks, and for these:

• Only include example logic specific descriptions and explanations in the example's readme
• put all "general" documentation into (a) separate file(s)
• Link to any "general" description/documentation that is needed for an example (e.g., address, seed, bureau etc. basically everything that also should have a proper docstring)

Are you suggesting to provide links like this for all the relevant objects / concepts: https://fetch.ai/docs/references/uagents/uagents-api/context?

@jrriehl yes, I envision the ultimate workflow something like:

1. maintain all object descriptions in docstrings
2. automatically populate docs from this codebase
3. manually add any descriptions for concepts / architecture that is not part of docstrings.
   Though ideally, from a usability perspective, we would use 'includes' not links, i.e., having each description written once and include them in all relevant places so they are displayed as part of the document, but only one place for us to update and maintain these descriptions. Theoretically speaking. Practically, I'm not sure yet about the effort and feasibility (we might at least also need a script to automatically extract all docstrings into a markdown/asciidocs file to reference in the examples readmes)