search

anvilresearch / connect-docs

Anvil Connect Documentation
16 stars 26 forks source link

Use a documentation site generator #21

Open adalinesimonian opened 9 years ago

adalinesimonian commented 9 years ago

In order to provide a nicer front to users other than a GitHub repository with markdown files in it, I think we should seriously consider a tool such as Sphinx and/or Read the Docs.

christiansmith commented 9 years ago

@vsimonian Read the Docs looks solid.

We've also looked at slate. DigitalOcean and Stripe are using it effectively, but it's worth noting that everyone seems to be using these more for API reference type docs than "guides" and general info.

Another option that's been on the table for API reference is swagger.io, which includes tooling for generating interactive docs from discovery documents (example).

Right now, this repo is organized so that we can use it easily with Hugo, the static site generator that currently builds https://anvil.io, from within the website repo. I started working on incorporating these docs into the site, but wanted to get a little further along with the rewrite first. We could also use some design help.

We may end up needing to use a combination of these tools to get the job done.