Make docs useful

[yuvipanda]

Currently, the hubploy documentation is scattered in a few places, and a few heads. This is issue is an attempt to getting the docs to a place where we can show off hubploy to people.

We intentionally structured the docs of TLJH in very specific ways, and it has worked out really well for us. We should try to copy that. We actually wrote documentation on how to structure our documentation - http://tljh.jupyter.org/en/latest/contributing/docs.html.

Primarily, I want us to have 3 kinds of docs:

1. "How-To" guides, where the title of each doc should complete the question "How do I...?". Examples of this would be "How do I set up an fresh repo for use with hubploy?", "How do I set up a local dev environment?", "How do I build an image?", "How do I add a new hub?", etc
2. "Topic" guides, that go into a single topic in detail. A very useful one would be the directory structure, how repo2docker is used, how authentication is done, how image pushing works, what kinda rights it expects on the cluster, values.yaml overriding, etc
3. "Reference" contains reference docs. I can think of hubploy config as the one right now.

I want us to use this issue to think of useful docs in these three ways, and write them one by one.

[yuvipanda]

There's a lot of useful content now in hubploy-template readme that could be here instead. I did add some useful info to the main doc page here though: https://hubploy.readthedocs.io/en/latest/

[salvis2]

I did always find it funny how the overwhelming majority of the docs were in hubploy-template rather than hubploy.

To start, do we want a divide in the docs between hubploy and hubploy-template? I feel like no, since hubploy-template is just the directory setup that hubploy expects. What would we want their ReadMe files to look like if we move the content to the docs?

As far as docs in those three categories go, what seems good to have setup first? My thoughts are (in no particular order, except maybe what I can think of that I could write):

• How to set up a fresh repo to deploy a jupyterhub with hubploy
• How to build an image for use with your hub
• How to set up a dev environment to contribute to hubploy / have a custom hubploy
• Reference docs for hubploy configuration (which I think is just describing all the options in hubploy.yaml?)
• Topic guide for directory structure
• Topic guide for values.yaml overriding

If you want to pick a couple I can plug away on those a bit in the next couple weeks. Gotta learn a bit of rST first.

[yuvipanda]

@salvis2 totally agree, re: hubploy-template :D Moving a lot of that here and referencing it from hubploy-template is probably way to go. Your ordering sounds great! Would love for you to take a crack at it...

Thank you for offering to put your time on this!

[salvis2]

@yuvipanda quite welcome! The first howto is well underway, mostly because it is the hubploy-template Readme (already in rST) with some updates.

How do you publish the documentation? Neither the GitHub Actions bit nor the CircleCI bit seem doc-related. I'm reading on the Sphinx website that you can build locally and output files, so I could test that way I think.

Relatedly, if you have a recommendation on testing the docs that is different than above, I welcome the input.

[salvis2]

First stab at documentation is at #78 .

[consideRatio]

@salvis2 @yuvipanda I wonder what parts of this issue you consider to be resolved by #78 and what action points remain to take for this issue. Thanks for your work on this ❤️!

[salvis2]

Of the 6 bullet points I put above, I did 5 of them. The last one I felt was out of the scope of my experience for now, but I added in the files so someone else can get right to writing the how-to if they want. I'll edit the comment above to be a checklist.

All three of the styles of documentation that @yuvipanda mentioned in the first comment have something on ReadTheDocs now, but there is more to write. I'll make a list from what I can think of right now and what I see from Yuvi's original comment that opened the issue. We should have docs on such things as:

• Using custom versions of Helm (primarily Helm 2 vs Helm 3)
• A contribution guide
• How-To Hubploy basic workflow (would probably refactor some of the main page's content into a How-To Guide and add some details on common ways to use Hubploy after JupyterHubs are deployed)
• How-to Hubploy multi-hub / multi-cloud guide
• How repo2docker is used
• How authentication is done
• How image pushing works
• What rights / permissions Hubploy expects on the cluster