Docs and test refactoring

[GeorgianaElena]

Before #549, I believe some maintenance work needs to happen.
This PR:

• moves repo_root/oauthenticator/tests to repo_root/tests (to be in line with other jupyterhub repos)
• changes the .rst files to .md files and hopefully much of the old syntax with myst markdown one

Note

The docs content was not changed more than a few typos I spotted here and there, to not bloat this PR more.

[consideRatio]

Wieee!!!! I appreciate that you do this chore work, as even reviewing markdown is preferable to me if additions are made later :)

Could you split apart this PR in two, where tests are relocated separately? I'm not feeling confident we can do that, but if we can and its okay, then I think its relevant to have in a dedicated PR to help highlight that in the changelog because its a possibly breaking change for people that relies on the tests, fixtures, or similar.

I'll come back and review the docs section as soon as I've completed the review on another PR!

[consideRatio]

I think this can be written directly in MyST markup. I parse the rST code to be invoking a sphinx directive, and that would match in MyST markup as described here: https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html

So it would become...

```{literalinclude} example-oauthenticator.py
```

Or perhaps this works?

```{literalinclude} example-oauthenticator.py```

[consideRatio]

Nice!! The docs parts LGTM and is ready to merge following review comments resolves, but I'm cautious to merging the test folder relocation as part of this PR as it could even be a breaking change. I hope you feel alright with splitting this PR in two!

EDIT: I opened jupyterhub/team-compass#588 to get further input on the topic of relocating tests.

[GeorgianaElena]

Haha, something strange happened. I've squashed the last commits, and I could see them squashed in the branch main...GeorgianaElena:oauthenticator:docs-refactoring, but not in this PR.

So I closed it, hoping to reopen it after and all to be fixed and updated. But now the reopen button is deactivated

[manics]

If you force push to a branch and the PR is closed it'll be disconnected (I guess GitHub assumes a force push means you've reused the branch for something else?)

[GeorgianaElena]

If you force push to a branch and the PR is closed it'll be disconnected

Very good thing to know 😅

I guess GitHub assumes a force push means you've reused the branch for something else?

Maybe 🤷🏼‍♀️ The other mystery thing is why the forced-pushed changes (commits squashing) didn't show up in the PR although everything seemed correct when checking out the actual branch.
I guess I manage to mess something up in between dropping, squashing and force-pushing commits