Create a new JupyterHub "landing page" at `hub.jupyter.org`

choldgraf commented 3 years ago

Description

Currently, we have some "about JupyterHub at a high level" documentation on the jupyter.org website, here:

I think that we should instead create a dedicated website to act as a splash page for JupyterHub, and host it at:

hub.jupyter.org

The splash page would have most of the information of jupyter.org/hub but might be laid a bit more nicely with some extra information.

To do

[x] Create jupyterhub.github.io and point it to hub.jupyter.org
[ ] Add the content and layout we want

Benefit

I think this would be valuable for a couple of reasons:

Our current "landing page" is nice, but embedded within the Jupyter website. This makes it less likely we will think to update it, and also means it is technically stewarded by a different team from the JupyterHub team. Having a repository host the JupyterHub website that is under the jupyterhub org will make it more likely that we notice and maintain it.
Having control of the templating etc would give us control over the layout and feel of the site. For example, we could largely re-create the Bokeh layout using a combination of the pydata-sphinx-theme as well as sphinx-design
The hub.jupyter.org could be a natural extension point for other URLs that are particularly important in our community. For example, it is easier to remember / copypaste team-compass.hub.jupyter.org than jupyterhub-team-compass.readthedocs.io. (this could also be a pattern that is followed more broadly in the Jupyter community.

Implementation

As I mentioned above, I think that it would be really easy to make something look quite nice with a combination of the pydata theme + sphinx design. I'd imagine that this page would be a high-level "showcase" of all the things you can do with JupyterHub, with links to other documentation in the ecosystem for people who want more information. Its goal would be to help point people in the right direction, and to look nice and appealing, rather than to provide complete information.

sgibson91 commented 2 years ago

I'd like to breathe life into this issue!

Running the Outreachy contribution period in Nov 22, it became very apparent, very quickly that JupyterHub does not have a clear pathway to explain (at a high level) what the project is about, how to get around, etc etc. Pieces of this information are dotted around our docs, but not centralised in a single place that is easy to find and easy to follow, particularly for folk who have never heard of a JupyterHub before.

Chris has some great ideas for implementation above, which we can continue to discuss, and I'd like to provide some ideas for content of this landing page.

What is Project JupyterHub about?
How does JupyterHub differ from Jupyter Notebooks, or just the term "Jupyter" (we should be brief with this as this is not really "our" problem to solve, but symptomatic of a lack of clarity from the Project Jupyter level)
(Optional) How is JupyterHub as a project different from those that might be backed by a company?
- This is optional as I believe it is an Outreachy-specific question when an applicant may be choosing between JupyterHub and, say, Mozilla to work with
- I think the crux of this is how can you expect the team dynamics to be different? E.g. JupyterHub is a globally distributed base of primarily volunteers, so how we work together is of a different style and a different pace to projects that have full-time paid devs and/or a headquartered office.
What skills are required to contribute to the project? (python packaging, kubernetes, sysadmin, etc)
What skills are we looking to add to the team? (e.g. react, accessibility, etc)
How to navigate around the organisation
... etc. please add if you think of anything else

As I mentioned before, we already have parts of this written up, they're just in distributed places. I also think we should try to revive the excellent work that was started in this PR as part of this!

https://github.com/jupyterhub/jupyterhub/pull/2726

sgibson91 commented 1 year ago

It would be really cool if we could embed the demo video into this page as well, now that it's published! https://www.youtube.com/watch?v=IhMHMuwphc0

choldgraf commented 1 year ago

I suggest at least to start we take these steps:

Create a jupyterhub.github.io repository that we can use for the jupyterhub org docs.
Ask whoever controls jupyter.org to register hub.jupyter.org and point to the GitHub DNS servers
Configure GH pages to serve to hub.jupyter.org

Then at least we only need to update our repo to make changes and don't need to wait for DNS etc

Any objections to that?

sgibson91 commented 1 year ago

@choldgraf are you able to lead on one or more of those action points?

choldgraf commented 1 year ago

I can give it a shot and see how far I get this evening or weekend 👍

choldgraf commented 1 year ago

Update: a skeleton site is live

Hey all, I've taken these actions:

I created https://github.com/jupyterhub/jupyterhub.github.io
I've added a skeleton Sphinx site with the jupyterhub-sphinx-theme
I've moved the jupyterhub-sphinx-theme to our organization (https://github.com/jupyterhub/jupyterhub-sphinx-theme)
I've updated the DNS entries for jupyter.org with a CNAME so that hub.jupyter.org points to jupyterhub.github.io

Still to do (by anybody, not just me!)

Add content, layout, etc to the Sphinx site that is at jupyterhub.github.io. This will then update hub.jupyter.org via a GitHub Action that builds the site.

sgibson91 commented 1 year ago

Thank you @choldgraf!

consideRatio commented 1 year ago

I've updated the DNS entries for jupyter.org with a CNAME so that hub.jupyter.org points to jupyterhub.github.io

This had some consequences for anything referencing jupyterhub.github.io that doesn't support being redirected. Thankfully for example helm install did so, allowing helm install commands to keep functioning.

In z2jh and binderhub's CI system we had curl -sS https://jupyterhub.github.io/helm-chart/info.json which didn't include the curl -L flag to follow redirects, so that broke.

choldgraf commented 1 year ago

Ah shoot - do you think we need to revert? Or is it ok to just document this and update URLs?

consideRatio commented 1 year ago

Since for example helm install can handle a reference to an URL that redirects by following the redirect, we are okay I think. I think the only thing that has broken is our own and other peoples curl scripts etc that may not be configured as relaxed as typical browsers or even helm as a CLI that does follow redirects.

Let's go with it at least until we learn about something bigger failing.

choldgraf commented 1 year ago

Makes sense - I guess one point to consider is that if people are relying on a specific address for stuff we might want it to be something that we control rather than a GitHub-generated one? But I don't feel super strongly about that

choldgraf commented 1 year ago

Blog list PR

Here's a PR that will pull the latest list of blog posts tagged jupyterhub on the jupyter blog!

https://github.com/jupyterhub/jupyterhub.github.io/pull/1

jupyterhub / team-compass