search

jupyterhub / oauthenticator

OAuth + JupyterHub Authenticator = OAuthenticator
https://oauthenticator.readthedocs.io
BSD 3-Clause "New" or "Revised" License
413 stars 365 forks source link

docs: a major refresher of the documentation #627

Closed consideRatio closed 1 year ago

consideRatio commented 1 year ago

We had a lot of legacy documentation around. In this PR I've gone through a lot of the documentation and tried to make it easier to maintain long term as part of making some updates.

For example, instead of writing again how to use GitLabOAuthenticator.allowed_project_ids, I let the gitlab specific docs link to the configuration reference that includes a good enough help string to be useful.

old new
image image

Related

consideRatio commented 1 year ago

If you have time @GeorgianaElena, I'd love a review of this as well. Thank you soo much for your help reviewing already in other PRs!!!

consideRatio commented 1 year ago

Argh sorry @GeorgianaElena, I requested a review a bit too early and pushed two commits with additional things =/

There is a docs build failure now, and it made me want to cover a bit more content while I'm at it. I'll comment again when its done.

consideRatio commented 1 year ago

Pweh! Okay @GeorgianaElena sorry for the noise, I did a final self-review of everything and pushed some details, it is now fully ready for review!

consideRatio commented 1 year ago

Thank you @GeorgianaElena for your help to review this so quickly!!!

consideRatio commented 1 year ago

Working on a separate PR I realized we needed default_role in docs/source/conf.py set to literal still, which makes the rST parsed helpstrings like `code?` format as code? instead of formatting as code?.

I pushed a commit to change that setting, and another to update docs/source/conf.py a bit to look more like the one in jupyterhub-python-repo-template.

consideRatio commented 1 year ago

There were notable differences in the .py files docstrings, where auth0 for example included a lot of outdated documentation and cilogon included caveats that I figure can be removed. I pushed another commit making them consistent, and making this view look consistent as well as a consequence:

image

@GeorgianaElena sorry for appending this PR with more and more after pinging for review. I'll stop now and open additional PRs instead with additional changes.

consideRatio commented 1 year ago

I didn't realize you approved this PR before Georgiana! I'll go for a self-merge to enable other PRs on top of this to be easier to review.

Thank you soo much for your help reviewing @GeorgianaElena!!!