Doc: Improve examples with use cases

[tomschr]

Situation

Thanks for this wonderful project! 👍 I'm slowly understanding it. 😉

Maybe others has the same difficulties than I. Although I really appreciate the examples, it was still a bit hard to follow. IMHO, the current approach has a gap between "A complete example" and "More real world examples".

It misses one use case which is needed most: having a bunch of plugin files in a specific directory and how to structure and use them with pluggy. I think, this is quite common and it should be covered.

Additionally, it would be helpful to share some "best practices". For example, how to structure and where to place specification and implementation.

Proposal

So my proposal would be to add a new section to fill this gap. Depending on whether you like this approach, we could go a little bit further. So here is a more ambitious change.

IMHO, I would propose the following structure:

• Use Cases
  • Creating a Simple Example
    That would be basically the content from the section "A toy example". Basically, it adds specification and implementation in one file.
  • Separating Specification and Implementation in Different Files
    That would be the content from "A complete example".
  • Discovering Plugins in Directories
    => That would be the new one
  • More real world examples

As you can see, the difficulty of the examples grow from easy to difficult.

Additionally, I would suggest:

• add a small paragraph when the respective example is most beneficial. For example, if you need to load the plugins dynamically, you would probably not use the simplest example.
• give recommendations how to structure your code and where to place specification and implementation. I think, this is not always clear from the text.

I would be happy to add a first draft if you consider this issue to be useful. 😉

[goodboy]

Hey @tomschr thanks for the docs improvement suggestions 😄

I'm always open to better docs and more examples so if this seems like something that would help you and others I would say we're at least willing to entertain the content and in the worst case include it as auxiliary reading material that can be pointed to from the main docs.

I'm more then happy to review and comment as I'm sure @obestwalter is (who wrote the "A complete example" material).

[tomschr]

@goodboy Thanks for your answer! 👍 I've looked at the documentation files now and it raises another question.

The whole documentation is almost stored into one, big file blob (index.rst) with almost 1000 lines. IMHO, it would be beneficial to split that into separate, smaller files. The reasons are similar to code (clearer, easier to handle, etc.) 😉

If you like that, I can do the split. However, that should probably go into a different issue/pull request as it is a separate topic.

What's your opinion on that? Should I start with splitting the content into different files first or just add my content to the existing index.rst file?