Move Documentation to readthedocs

[AlecRosenbaum]

Right now all the documentation for this library is in README.md. It's getting pretty unwieldy at this point, and should really probably be moved into a hosted page somewhere.

I've used readthedocs.org before, and it works pretty well. We'll have to refactor the README documentation into sphinx documentation first, but that shouldn't be too tricky.

Tasks:

• refactor documentation into a docs/ folder, using sphinx
• enable/connect readthedocs
• update README.md
  • to point to the hosted documentation
  • to only have a feature overview and basic quickstart
• (maybe) update repo description with the docs link

[tsx]

Suggesting an alternative: github pages?

[AlecRosenbaum]

I don't know if there's a clean way of using GitHub Pages with Sphinx, which I'm assuming we want to use. I think if we wanted to use GitHub Pages, we'd have to build sphinx in CircleCI and push it back to a special branch here for github to serve.

[philfreo]

(GitHub Actions may allows you to do that, I've seen examples of people committing back from there)

[tsx]

You can commit to /docs in master if a separate branch is not a good fit. https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source

I would like to suggest MKDocs instead. It uses markdown instead of reStructuredText, and it's lighter and easier to configure. — a bit like this library vs. Celery.

Another selling point is that it comes with a command to automatically build and push the result to the gh-pages branch, so it effectively publishes the documentation to GitHub pages (of course, you can build it and post it to another place.)

Example: https://jpscaletti.github.io/proper-form/

[sixhobbits]

Here's a preview of what it could look like using MkDocs Material -- a more modern theme of MkDocs that includes a lot of nice extras like search.