Add Sphinx documentation

[emiliom]

With a conda package now available, it seems like a good next step would be to create some minimal Sphinx documentation, mainly to document the REST API's -- which ones are available, their usage, etc.

I realize there's a test endpoint somewhere, and its swagger interface provides good documentation. But relying on a test endpoint for general documentation may be a little frail? Would be cool if you could leverage some of that swagger stuff to "export" static HTML or markdown/ReST that could be incorporated into the Sphinx docs ...

Anyway, not saying this is a high priority. Just creating this issue while the thought is in my head. We can discuss at the next BiGCZ/ODM2 call.

[lsetiawan]

But relying on a test endpoint for general documentation may be a little frail? Would be cool if you could leverage some of that swagger stuff to "export" static HTML or markdown/ReST that could be incorporated into the Sphinx docs ...

Now you're getting fancy 😉

[emiliom]

Now you're getting fancy

I resent the implication that I'm not usually fancy :expressionless:. I think. Or maybe it's a compliment :confused:

[lsetiawan]

Not really sphinx currently, but here's a static of the Swagger documentation: http://odm2.github.io/ODM2RESTfulWebServices/

It was created with http://editor.swagger.io/.

[emiliom]

Very nice!! Who cares that it's not Sphinx, specially if it saves effort by leveraging Swagger directly. This is what I was looking for.

Longer term, it's still probably a good idea to create Sphinx docs, but for the REST API documentation it would just link to this Swagger page.

[emiliom]

OMG, you already updated the repo header to show the link to this static swagger docs! You're good!