API docs generation for Docs v2

[hsanjuan]

This issue is to discuss what to make of this library for the upcoming v2 docs:

cc. @jessicaschilling @johnnymatthews

It seems https://docs-beta.ipfs.io/reference/http/api/#getting-started includes the generated HTTP API docs, but I am not sure if they were changed by hand or it is the raw output from here.

I'd like to know if this library needs maintenance, and if we put time into the maintenance, what things do you want out of it. Alternatively we should signal clearly if this is dropped or deprecated.

Maintaining API documentation manually is a very painful process that luckily no one had to go through in the last years, and still we have fairly updated and accurate API docs. So my personal recommendation is to keep this, even with it's shortcomings.

Things that could be improved if we decide to keep this around:

• Go all over the docs and fix wordings, improve descriptions etc in go-ipfs so that they make sense for both CLI and HTTP.
• Add HTTP-Specific descriptions to go-ipfs when they don't fit.
• Add manual specification for of the most problematic endpoints (essentially /add), which describes how to actually add folders, the multipart types etc.
• Add more descriptions about general API features that affect several endpoints (stream errors, trailer headers).
• Improve formatting of generated text, anchor links etc
• Automate generation process on every new release
• Potentially generate multiple pages (one per endpoint) rather than a single one (I am really against this, but it has been brought up).
• Include fetching/generation of js-ipfs HTTP API docs
• Document potential differences between the written Spec and the actual implementations.
• ...

[jessicaschilling]

These did indeed start with the generated API docs but needed quite a bit of massaging (mainly search/replace to escape out things that didn’t render correctly in markdown, IIRC) to display properly. (Note that the result of not escaping out errant characters was that the page just stopped rendering at that point.)

I know @johnnymatthews has both experience with and ideas for API docs going forward, as well as an epic-sized issue in the docs repo as a placeholder for discussing this matter, so I’ll let y’all chat further.

[jessicaschilling]

Also see: https://github.com/ipfs/docs/issues/393

[hsanjuan]

These did indeed start with the generated API docs but needed quite a bit of massaging (mainly search/replace to escape out things that didn’t render correctly in markdown, IIRC) to display properly. (Note that the result of not escaping out errant characters was that the page just stopped rendering at that point.)

ok, so that massaging should happen in the generator. I can diff things and get the generator produce exactly what the v2 docs show now.

[lidel]

Continued in ipfs/ipfs-docs#267