Minor tweaks to the readme

[consideRatio]

Updated PR description

This PR makes some minor tweaks to the README file that I think improved it slightly.

1. servers -> delete:servers scope
2. --cull-admin-users flag listed
3. Single quotes transformed to double quotes in example configuration to be black compliant
4. Referenced role name idle-culler and referenced service name cull-idle have been renamed to jupyterhub-idle-culler-service and jupyterhub-idle-culler-role.
5. Some other small tweaks in text were attempted towards improved readability

Outdated PR description

I note that read:hub is required, and I think we only need the delete:servers rather than read:servers but would love a confirmation on this idea.

Note that the reason we need read:hub is because we access the /hub/api/info endpoint for a version check of the jupyterhub we work against.

jupyterhub-idle-culler/jupyterhub_idle_culler/__init__.py

Lines 160 to 167 in ae59078

	# Starting with jupyterhub 1.3.0 the users can be filtered in the server
	# using the `state` filter parameter. "ready" means all users who have any
	# ready servers (running, not pending).
	auth_header = {"Authorization": "token %s" % api_token}
	resp = await fetch(HTTPRequest(url=url + "/info", headers=auth_header))
	info = json.loads(resp.body.decode("utf8", "replace"))
	state_filter = V(info["version"]) >= STATE_FILTER_MIN_VERSION

Related

jupyterhub/zero-to-jupyterhub-k8s#2434

[consideRatio]

Woops need to make some refinements to the associated text.

[consideRatio]

I made some misc changes to the README while updating this. I made some comments to spot the actual relevant changes besides some opinionated format changes aligning with black.

[consideRatio]

I thought it was hard to keep track of a registered service name like idle-culler, a role name like cull-idle, and a cli name jupyterhub-idle-culler --- so I opted to name them all jupyterhub-idle-culler and mentions here "the configured culler service" to decouple from whatever name is used.

[minrk]

This is always hard for me! I see both different names for each kind of thing, and using the same name for everything as sources of confusion. I like what you have here.

To me:

• Downside of different names: more names to keep track of
• Downside of the same name: it's harder to see which ones matter that they match (e.g. the role name and service name don't have to be related, but the service name does have to match the name in the services list in the role)

[consideRatio]

I think my main objection isn't naming them different things, but that the name cull-idle as a service name and idle-culler as a role name felt too arbitrary.

I have seen two practices when naming k8s resources, where the dominant have become to use the same name without adding a suffix of -<type>, but adding a suffix have also been used for the purpose of clarifying the resource type.

Do you think it would be a better compromise to have a name for the role as jupyterhub-idle-culler-role and a name for the service as jupyterhub-idle-culler-service ? Then, it would be quite clear I think, and it would not make me confused about what cull-idle (service) vs idle-culler (role) is for example.

[consideRatio]

I pushed such changes to this PR!

[minrk]

I actually have a general preference to avoid redundant names (e.g. service hub-service, pod hub-pod, role my-role), but I think it's a fine compromise in this case, and there's no need to spend too much time picking a few strings in an example!

[consideRatio]

I made this a dedicated section, so it wasn't listed specifically for managed/unmanaged setup.

[consideRatio]

I suggest we go for a 1.2.1 release with this and #35 in, what do you think @minrk?

[minrk]

@consideRatio go for it!