New example doc format

[derek-globus]

Added a new heirarchy called "Updated Examples" under experimental docs.

Most of these example pages are stubbed out for this PR; rather the goal is mostly to agree on a better example heirarchy which we can go fill in (which may be as simple as a copy/paste in some examples) once there's slots for them.

Notable changes:

• Top level heirarchies - categories of examples so that users are met with less of a wall of text when looking at examples
• Example titles rewritten with active verbs - I renamed examples to be uniformly named like "doing thing X" instead of just "thing X" as these examples should show users how to do particular things.
• Removed the groups listing example (this becomes a simple 5 line code script with GlobusApp and doesn't feel necessary to maintain)
• Merged native_app.rst and client_credentials.rst into a common login_flows.rst page.

---

📚 Documentation preview 📚: https://globus-sdk-python--1008.org.readthedocs.build/en/1008/

[kurtmckee]

I'm guessing that submit_transfer/ and schedule_transfer/ are expected to have example files that could stand to be grouped in the same subdirectory, but is there an expectation that task_deadlines and recursive_ls make more sense to deviate from that?

[sirosen]

I think each should be using /index pages, but it doesn't need to happen this minute.
We moved several of these to dirs to be able to make their example scripts separate files which are available for download. I would like to employ that structure everywhere, but we can partially do it as we work through these examples and fill them out.

[derek-globus]

I would like to employ that structure everywhere, but we can partially do it as we work through these examples and fill them out.

That was basically my thought.

• Certain examples will have their own file structure linking to scripts.
• Certain examples will be a single file with inline code references.

I'm not sure which camp each example will fall into but as I fill them in, I'll be editing them into the more accurate one.

[sirosen]

I would not characterize either case as typical. In my experience, our users break into three basic groups:

• those who are writing tools against fixed collections (both ends fixed)
• those who are writing tools against one fixed collection (one end fixed, one end open)
• those who are writing generic tools (both ends open)

And the latter two groups are more similar than the first.

If anything, knowing both of your collection IDs ahead of time is the exception, not the rule.

Do I object to the ordering used in this doc, or the overall presentation? Eh. Definitely not strongly, but this note jumps out at me and makes me feel that something is slightly amiss. I'm not sure, but I think that we should actually have a preamble that says:

• if you know one or both of your collection IDs, do it this way
• if you don't know the collection IDs, do it that way

with intra-document links.

[derek-globus]

Hmm, I can take another stab at this doc with the preamble you suggest.

[derek-globus]

Updated the doc to be less assumptive; lemme know what you think now.

Updated Doc: https://globus-sdk-python--1008.org.readthedocs.build/en/1008/experimental/examples/transferring_data/submit_transfer/index.html

[sirosen]

I think each should be using /index pages, but it doesn't need to happen this minute.
We moved several of these to dirs to be able to make their example scripts separate files which are available for download. I would like to employ that structure everywhere, but we can partially do it as we work through these examples and fill them out.