Open AlecRosenbaum opened 4 years ago
Suggesting an alternative: github pages?
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.
(GitHub Actions may allows you to do that, I've seen examples of people committing back from there)
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.)
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.
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:
docs/
folder, usingsphinx
README.md