Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move Documentation to readthedocs #152

Open
6 tasks
AlecRosenbaum opened this issue Oct 25, 2019 · 6 comments
Open
6 tasks

Move Documentation to readthedocs #152

AlecRosenbaum opened this issue Oct 25, 2019 · 6 comments

Comments

@AlecRosenbaum
Copy link
Contributor

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
Copy link
Contributor

tsx commented Oct 31, 2019

Suggesting an alternative: github pages?

@AlecRosenbaum
Copy link
Contributor Author

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
Copy link
Member

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

@tsx
Copy link
Contributor

tsx commented Oct 31, 2019

@ghost
Copy link

ghost commented Nov 29, 2019

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants