docs: API documentation tool

[lnielsen]

E.g. https://github.com/tripit/slate

[nharraud]

tripit/slate

• Pros
  • Nice documentation, used by a lot of companies.
  • Markdown format even readable in Github
• Cons
  • Very simple markdown format (also an advantage in some way). No syntax to specify error codes, parameters, etc... . This is for really high level doc with lots of examples.

sphinxcontrib-httpdomain

• Pros
  • Quite complete syntax: request headers, query parameters, json body parameters...
  • Part of the documentation can be in the code and part outside, avoiding bloating the code with examples and at the same time avoiding duplication of doc in code and outside. claimstore example
• Cons
  • It is possible to specify json parameters in the request body but I don't see any way to say that it's also valid for other formats (ex: xml)
  • Output is not as nice visually as tripit/slate.

@lnielsen @jirikuncar @tiborsimko
Just to be sure, what are the use-cases for this documentation?
1/ one doc per module containing a REST API
2/ helping services generate their own documentation by aggregating the doc from all rest apis registered on an app?

The main constraint is that we know that some modules will have more than just the REST API so we need a sphinx doc for the rest of the code.
Another constraint, if we go for multiple instances of one module api with different endpoints (as proposed here inveniosoftware/invenio-records-rest#9), is that we can't use the module documentation "as is" for the service api. The endpoints would not match.
What's more, as some services will have custom behavior depending on record metadata fields, (like we plan to do for B2Share), the service doc would be missing some important parts.

For module documentation I would use sphinxcontrib-httpdomain as we already use sphinx for the rest of the code, and leave services in charge of their own API documentation.

As the markdown format is simple, it might be possible to bootstrap a doc from the sphinx one if it is really needed, that way the endpoints would be valid. This could be done in a third-party module.

[lnielsen]

For my concern it's (2). Help services to create really good beautiful REST API documentation (which is critical for adoption of an API).

I don't think it will be possible to use auto-generated documentation, as it won't be specific enough for each instance.

[lnielsen]

If needed, we could do a invenio-rest-docs module where all this API documentation helpers exists.

[lnielsen]

Another points is that per service you might want a coherent view - e.g on Zenodo I won't not one REST API documentation but also integrate the OAI-PMH API documentation.

[nharraud]

I'm not sure to follow. If we don't provide the services' API doc content, what would be providing invenio-rest-docs which would not be already in tripit/slate for example?

From the top of my head I can see one use case only: Helping the service developer make sure that their API has documented the last features provided by all invenio modules. It could be done automatically in travis/jenkins/younameit and does not imply generating the service's API doc.

[tiborsimko]

For module documentation I would use sphinxcontrib-httpdomain as we already use sphinx for the rest of the code, and leave services in charge of their own API documentation. As the markdown format is simple, it might be possible to bootstrap a doc from the sphinx one if it is really needed

Seems interesting. The sphinx docs are good for the framework developers (the docs staying close to the code), the httpdomain extension does a good job for REST API semantics and formatting already, and if services are able to "collect" these docs for even prettier reformatting, then so much the better.

[hachreak]

... and what about swagger? (now called OpenAPI Initiative )

You can:

• document API in a YAML format
• quickly write clients for many languages (e.g. for python)

You can have a look to an example of API description and a demo website that show documentation.
The Try it out is really interesting I think!

[jirikuncar]

You can also watch a EP2016 talk about Flask-RESTPlus which is using Swagger UI (https://www.youtube.com/watch?v=OTWs0wPHU-g).

[kaplun]

Also ORCID is using Swagger. https://pub.orcid.org/v2.0_rc1/

[lnielsen]

Personally I really dislike Swagger style of documentation compared to the style from e.g. slate.

Btw, there's also e.g. http://jsonapi.org when we talk about standards.

[MikeRalphson]

@lnielsen I have written up a comparison of four tools which can convert OpenAPI / Swagger definitions into Slate-compatible markdown, in case it's of any interest?

There's also a more Slate-like theme for Swagger-UI here