Sort out the documentation about requests-oauthlib

[ib-lundgren]

Looking at the docs on RTD as they are now it very much is just API docs, even when including #46. There is no clear indication of where to start if you are completely new and just landed there. I think we might need

1. Some welcoming text in the index.rst page introducing people to the documentation.
2. A tutorial (or tutorial section even) showing fully working examples for people wanting to jump in quickly without getting bogged down in details of why right from the start.

Suggestions on tutorials:
OAuth 1 showing Twitter or Bitbucket
OAuth 2 showing Google, Facebook or Github.

I quite like having lots of docs in source but don't feel strongly about it so feel free to move them =)

Regarding clarity in API docs, I'll try and look over these but it would help a lot to have someone go around and say "This section here is completely incomprehensible, what do you mean by X and where did Y come from? Why do I need Z?" etc.

[Lukasa]

Both good ideas, I've added them to the list. =)

I can't progress this now because I'm at work, but I intend to look over the API docs at some point for exactly that purpose. I'll open an issue when I do (unless someone else does it first).

[ib-lundgren]

Started off a new umbrella PR for tutorials in #49.

[rubik]

I find the OAuth2 Workflow page really messy and inconsistent.
https://requests-oauthlib.readthedocs.org/en/latest/oauth2_workflow.html

For example, the WebApp Flow is first presented, then all the workflows are listed (and here you are redirected above), and then there are other slightly less related things, like refreshing tokens.
I think the page structure should be:

• Introduction, which is currently missing, explaining the Available Workflows.
• Web Application Flow
• Mobile Application Flow
• ... &c., all the flows ...
• Refreshing tokens (like now, with all the subsections)

[ib-lundgren]

This is excellent feedback! Will see if I can find some time to address
these structural fixes and missing sections this week. Please let me know
if there are any specifics you want me to include/answer and about any
other wishes you might have on other sections of the documentation.

On Sun, Aug 25, 2013 at 4:15 PM, Michele Lacchia
[email protected]:

I find the OAuth2 Workflow page really messy and inconsistent.
https://requests-oauthlib.readthedocs.org/en/latest/oauth2_workflow.html

For example, the WebApp Flow is first presented, then all the workflows
are listed (and here you are redirected above), and then there are other
slightly less related things, like refreshing tokens.
I think the page structure should be:

• Introduction, which is currently missing, explaining the Available
  Workflows.
• Web Application Flow
• Mobile Application Flow ... &c., all the flows ...
• Refreshing tokens ** Like now, with all the subsections

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/48#issuecomment-23229394
.

[rubik]

Great! So I'll just add a minor thing: in the tutorials and the web workflow raw_input() is always used to avoid web frameworks' specific handlers, but it would be helpful to see a real-world case. I call it minor because I still have to integrate OAuth in my web app, so I don't know how difficult it is yet.

Thanks.

[Lukasa]

So I've taken a pass at a substantial rewrite of that section. Take another look and see if you think it's improved.

[rubik]

Really much better in my opinion! Thanks!

[ib-lundgren]

@Lukasa ⭐

@rubik Would something like https://gist.github.com/ib-lundgren/4487236 be helpful as a "real case"? or did you have something else in mind?

[rubik]

@ib-lundgren: Yes, exactly something like that! OAuth2 is even easier, so the example should be even simpler.

[ib-lundgren]

@rubik will create one for OAuth 2 then. I have some quality docs time coming up next week so if you have more suggestions don't hold back.

@Lukasa what do you think about including less "pure" examples in the docs? i.e. ones using Flask or Django

[rubik]

what do you think about including less "pure" examples in the docs? i.e. ones using Flask or Django

That would be great. Examples with raw_input are useful to try out the library but not in the real cases. Github's docs for example link to this (from https://developer.github.com/v3/oauth/):
https://gist.github.com/thruflo/e3fbd47fbb7ee3c626bb

As you can see it's still quite "pure". All the handlers are implied so that it remains framework-agnostic.

[ib-lundgren]

@rubik A fully working example using Flask/Github - https://gist.github.com/ib-lundgren/6507798

Will create a web framework agnostic docs only version and add that next.

[rubik]

@ib-lundgren Splendid, thank you!

[ib-lundgren]

Looking at the docs and skimming http://jacobian.org/writing/great-documentation/what-to-write/ I think we kind of have some "topical guides" and "api reference" but except for the short examples (they really are not tutorials) we fall short on the absolute beginner docs. Improved landing page will help here and maybe adding "Getting Started with OAuth 1" and "Getting started with OAuth 2" sections would be helpful.

I am pretty bad at writing docs and tend to use 15x more words and details in some chaotic mess that on a good day might be confused as structured content. That said I'd be happy to try and take a stab at the getting started tutorials if some heavy editing is supplied :)

[shazow]

Fwiw, I found the code samples in the Tutorials section to be the most useful. The Flow examples were a bit confusing (except for the part about the various ways to handle refresh tokens, but I feel that should have come later). +1 on less raw_input and more real webapps.

If I were to restructure the docs, I'd focus primarily on OAuth2. Start with a very brief truncated code example of OAuth2, linking to the full Web App example for the complete code. Then go into the supported scenarios/workflows and respective examples.

I'd rename "Tutorials" to "Examples", since it's just code snippets for the most part, not really step-by-step tutorials.

If this sounds good, happy to send a PR.

[rubik]

@ib-lundgren That plan sounds good. Also, very interesting link.
@shazow I agree on everything!

[ib-lundgren]

Sounds great! :-)
On 1 Oct 2013 13:46, "Andrey Petrov" [email protected] wrote:

Fwiw, I found the code samples in the Tutorials section to be the most
useful. The Flow examples were a bit confusing (except for the part about
the various ways to handle refresh tokens, but I feel that should have come
later). +1 on less raw_input and more real webapps.

If I were to restructure the docs, I'd focus primarily on OAuth2. Start
with a very brief truncated code example of OAuth2, linking to the full Web
App example for the complete code. Then go into the supported
scenarios/workflows and respective examples.

I'd rename "Tutorials" to "Examples", since it's just code snippets for
the most part, not really step-by-step tutorials.

If this sounds good, happy to send a PR.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/48#issuecomment-25445655
.

[JonathanHuot]

The documentation has been improved a couple of times across this ticket and probably the description does not reflect the current state. I'm suggesting to close it. Feel free to create another one with latest remarks about doc if necessary.