The majority of the current example code mimics a CLI. It does this in a very generic way with indirection and parsing arguments to discover module names. This is very clever and effective but it is not very instructive to users who are likely new to OpenStack and possibly even new to Python.
Consider this, if a user new to the SDK asked for example code to create a server, what file would you link them to? If it's example/create.py then that user will be lost almost immediately since there is nothing about creating a server in that example. They would need to understand the example code deeply just to decipher how to create a server.
The number one property of examples is that they should be instructive. We can make them instructive by making them simple, straight-forward, and easily understood. They can be simplified by making them linearly readable without having to bounce around to many source files to understand one example. They can be straight-forward by having them designed for one purpose (e.g. listing compute resources, creating block storage resources, etc). And they can be easily understood by having them split into separate and stand-alone functions.
Some nice properties emerge when we follow these principles. The example functions are testable, ensuring ongoing quality. We can display the functions from within the user guides using literalinclude with the :lines: option. That means that not only are our examples tested but our user guides are tested too!
All of this also make the examples very easy to copy/paste from. This a very important property for busy developers. If you've ever written example code for a popular SDK before, you'll know this as you'll see the example code you've written reflected back at you in StackOverflow, forums, and email. It makes you want it to be the most clear and concise code you've ever written because it gets used everywhere.
I agree, but I'd like to keep some bits useful for developers. I use examples/
I think it'd be great if we discontinued a lot of CLI argparse support and just used OCC.
The only other example I use a fair amount is examples/list.py, but maybe that could go.