Expose dedicated API docs to replace "not found" page
During the retrospective we were briefly discussing the state of our API docs.
- Our "API documentation" is currently the Not Found page of openQA
- API is documented inline, but very incomplete and not well-maintained
- Actual inline documentation should be used for internal API
- The POD format is not particularly well-suited to REST APIs
- Even to confirm what behaviors are supported or expected is currently non-trivial with many features
- We should pick topics to document and select what we support (e.g. REST API vs. UI-support helpers vs. experimental routes)
- API docs should be published online
- Slate is a fairly well-established tool
- Markdown is widely supported
- Generated docs should be published on open.qa
Note that if we create inline comments manually we can also maintain a markdown document manually instead. To me the maintenance effort of an extra, manually written markdown document (e.g. using Slate) is not higher than maintaining POD comments. The only difference is where the changes would be made. So we would not need some complicated generator here to improve. So if you had a tool for exporting the Mojolicious routes and POD comments directly into a nicely formatted document in mind: Yes, that would likely not be feasible but we also don't need it to improve.
So the source for documentation would be markdown?
I personally would prefer to have something in YAML, from which we can generate Markdown.
Having a data file (or several files) will enable us to do more with it than just generating documentation.
For example automatically generate tests.