Reformat Examples

[jtroussard]

Am interested to receive feedback on reformatting the examples to make them easier to maintain, and setup. Currently I noticed there are a few issues with the current format of the examples:

1. They are not the easiest to set up and run. Users have to copy the code block from the .rst file, clean it, and manually update.
2. Some examples that become outdated and broken and when contributions are made to maintain these files, there is no easy to test/verify the changes.

I would purpose that the structure of the examples adopt a more modular suite approach.

docs
|   
- - - -examples
    |   examples.rst <- README.md for examples/maybe contribution guide
    |
    - - - -real_world_example
    |       real_world_example.md
    |       real_world_example_test.py
    |       real_world_example_config.py
    |       
    - - - -google
    |       google.md
    |       google_example.py
    |       google_example_test.py
    |       google_example_config.py
    |       
    - - - -linkedin
    |       linkedin.md
    |       linkedin_example.py
    |       linkedin_example_test.py
    |       linkedin_config.py
<and so on>

Of course this structure is just an example to transmit and overall idea. Different testing/config frameworks could be applied as well. While a departure from the simple examples setup from before this offers several benefits:

• Allows for periodic tests to ensure examples remain up-to-date.
• Allows for periodic tests to detect any major interface changes with popular API owners.
• Allows for contributions to examples to be verified and tested without having to set them up manually and independently run them.
• Allows for examples to include configuration values like scope, ids, etc.
• Individualized README files for each of the examples could provide context for style or protocol differences.

Draw backs to this approach is that the examples themselves become a little heavy.

• Introduction of new examples would require more then a quick 20-30 lines in a code block.
• Automated tests would require accounts be created for those API owners who don't provide test credentials.

Interested in feedback. Willing to take on this effort if Repo Owners/Admins would allow for the github secrets feature be implemented to store test account api credentials.

[jtroussard]

After thinking about this for a while I realized the only way to implement it would be to have accounts registered to this library to obtain client id/keys. There seems to be a section in GitHub settings that might be able to store this data securely. Not sure if it is a good idea to move forward though. Who would be owner of the accounts of the resource providers? Will leave this up for a little while longer.

[JonathanHuot]

Would be very interesting to see it for real. If stored securely, I suppose it is safe to put personal tokens there.. Note it can be interesting to start with a skeleton/example/documentation section on how to create one of these sections. That way everyone could add his own provider tests.

[JonathanHuot]

I have added python code in a separate file, and it makes maintenance and copy/paste (!!) much easier.

See https://requests-oauthlib.readthedocs.io/en/latest/examples/native_spa_pkce_auth0.html
See https://github.com/requests/requests-oauthlib/blob/master/docs/examples/native_spa_pkce_auth0.rst

The next step would be to add unit test with environment variables and integrated into GitHub Actions.
Any web testing framework to recommend ? Selenium or something similar?

[JonathanHuot]

Closing as it is now part of 1.4.0 / #530