Revamp our documentation and refactor a bit

[choldgraf]

This updates our documentation to make it a bit easier to navigate and understand. It also makes some content improvements along the way.

Docs preview of this PR is here

Here are some major things that this PR tries to improve:

• The get started guide is now a tutorial, meant to be followed step by step, in line with how Diataxis recommends tutorials be used. It now has fewer information, and focuses specifically on "getting started"
• The howto section has been renamed the user guide, and now groups pages based on major topic area (e.g. Configuration, Deployment, etc).
• The giant list of configuration files is broken into sub-sections based on the kind of workflow they're attached to (e.g. datascience) to make it easier to parse.
• A lot of content has been consolidated and-or moved around to make it easier to find the right information in one place.
• Some updates to styling so that we hide sidebars when they aren't needed, improvements to the dark-mode logo, etc.
• Updating a lot of content to markdown so that it's easier to maintain and improve.
• Uses the dirhtml builder for "clean" URLs. If we merge this, we should enable clean URLs with readthedocs so that any direct links will properly redirect

More updates

• Adds a little guide on when to use repo2docker in different scenarios.
• Creates a short how-to for each scenario with example code and external links.
• Updates the landing page so that it's more visually appealing and quick to parse, and "feels like" a landing page.

It probably could use a pass or two to double check that the structure works and that I haven't missed something. Happy to iterate with feedback if folks would like.

[yuvipanda]

/cc @chuckwondo who has helped with related docs to take a look if he can :)

[chuckwondo]

Thanks for tagging me @yuvipanda.

@choldgraf, thanks for the reorg. Your description of the reorg sounds great, and I've added a few comments, but I haven't gone over it in great detail. If I could see it all properly rendered, it would be much easier to provide comments regarding the layout/reorg, and go through it all in detail. Is that possible without my having to pull it down and run the doc server locally?

[yuvipanda]

@chuckwondo you can see it in https://repo2docker--1433.org.readthedocs.build/en/1433/! That link is accessible via the tests - it's the read the docs

[choldgraf]

The latest PR adds a bit more content using some slides from a presentation that @yuvipanda has given a few times about repo2docker. Here are some highlights (copied to the PR body as well):

• Adds a little guide on when to use repo2docker in different scenarios.
• Creates a short how-to for each scenario with example code and external links.
• Updates the landing page so that it's more visually appealing and quick to parse, and "feels like" a landing page.

I think this is ready for somebody to take a pass at it - many thanks for the review @chuckwondo - I'll get to your questions when I take another pass after you or somebody else gives it a look.

[rgaiacs]

Great revamp of the documentation. I added minor comments. I'm happy for this to be merged and further improvement to be made in new pull requests.

[choldgraf]

I believe that I've addressed all of the comments except for a couple. I'm not sure whether we recommend "just" repo2docker or the full jupyter-repo2docker, I'm also not sure what our policy is on calling them container images vs. Docker images. Could we resolve those in a follow-up PR? This one is already quite beefy!

[rgaiacs]

Yes, I can send a PR covering the use of "container image".

[choldgraf]

Feel free to ping me and I'm happy to review. Shall we merge this one and then iterate there?

[rgaiacs]

Shall we merge this one and then iterate there?

Yes. 👍 to merge.

[choldgraf]

OK cool - let's wait a couple hours to see if @chuckwondo wants to give another pass, but I think I addressed his questions, and given your review i think it's safe to merge. I'll merge if he doesn't ask us to hold off. Happy to iterate with y'all further

[chuckwondo]

I really like the reorg and the clarity! Thanks!

[chuckwondo]

Consider pulling these cases out into a bulleted list for better visibility/readability.

[choldgraf]

Thanks @chuckwondo for the extra comments - I've gone through and made another round of edits to address your suggestions. Thank you to both of you for your help.

I'll merge this one in since we have one explicit and one implicit approval, and please ping me if y'all would like to iterate on the content more from here!