Migrate documentation from gitbooks to readthedocs

[frenchfrywpepper]

Issue #69

• Scope what's required to set up read the docs
• Create a readthedocs account for the https://github.com/stitchfix/hamilton repo, add multiple administrators
• Enable build on merge to main, this will be published as the 'latest' documentation version
• Create some configuration in the docs folder to tell read the docs how to behave
• Create some configuration in the docs folder to use sphinx/rst/furo theme, etc
• Move the .md files from the documentation branch and reconfigure them as .rst
• Determine how it would function and be rebuilt.
• Read the docs will automatically build on merge to main, and publish as latest
• If you want to add another 'version' you can activate a new version in the read the docs settings for the project, this can be done by branch or tag
• If you don't want to build 'latest' from main you can turn that off
• Get something set up -- determine styling.
• In this PR I have something setup and working, with minimal style. It's building "hamilton-temp" documentation from my fork.
• You can see the 'readthedocs' version here: https://hamilton-temp.readthedocs.io/en/readthedocs/
• You can see the 'latest' version here: https://hamilton-temp.readthedocs.io/en/latest/index.html
• I've created placeholder pages for all of the current docs, this is to ensure the TOC is working as desired
• Only the intro page has content and links and such, if we like this direction the next step would be to convert more pages to rst
• This setup is using the furo theme, further customization is possible, but I'd recommend getting all of the content moved over first.
• Plan migration from gitbooks.
• Get all the content moved over to rst on the 'main' branch of hamilton
• Setup all of the versions to be built
• Turn off gitbooks?
• Delete 'documentation' branch

Changes

Creates a docs folder which will replace the 'documentation' branch. Docs folder is configuration for readthedocs with sphinx.

How I tested this

By setting up a hamilton-temp readthedocs project: file:///Users/sarahhaskins/dev/frenchfrywpepper/hamilton/docs/_build/html/index.html

Notes

Checklist

• PR has an informative and human-readable title (this will be pulled into the release notes)
• Changes are limited to a single goal (no scope creep)
• Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future TODOs are captured in comments
• Project documentation has been updated if adding/changing functionality.

[skrawcz]

https://hamilton-temp.readthedocs.io/en/readthedocs/

Ooo looking good! CC @elijahbenizzy.

[elijahbenizzy]

These look 🔥

[elijahbenizzy]

Fo migrating we should just have gitbooks have one page that links to RTD?

[skrawcz]

Thanks @frenchfrywpepper! What's the best way to review this? Should we schedule some time? or?

[frenchfrywpepper]

@skrawcz If you want to schedule time, that's fine. Otherwise, it's best just to look at the output: https://hamilton-temp.readthedocs.io/en/readthedocs/

[skrawcz]

follow up:

• add icon logo
• how to not hardcode links

To go live:

• merge this (no harm)
• give the site a walk through / update anything that's stale
• ask for feedback
• switch links
• create redirect

[CharityKithaka]

Hey, @skrawcz . I had a question. I am writing about how they can not hardcode links in the docs folder or am also replacing the hardcoded links in the reST docs folder in the project. Or am doing both?

[skrawcz]

Hey, @skrawcz . I had a question. I am writing about how they can not hardcode links in the docs folder or am also replacing the hardcoded links in the reST docs folder in the project. Or am doing both?

The latter, so replacing hardcoded links in the reST docs folder would be the task please :)