search

berkeley-dsep-infra / hubploy

Toolkit to deploy many z2jh based JupyterHubs
BSD 3-Clause "New" or "Revised" License
16 stars 15 forks source link

Make docs useful #67

Open yuvipanda opened 4 years ago

yuvipanda commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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):

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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

First stab at documentation is at #78 .

consideRatio commented 4 years ago

@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 :heart:!

salvis2 commented 4 years ago

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: