RPC API reference: document global flags

[aschmahmann]

Flags like --offline , --cid-base, --timeout, etc. are not documented in https://docs.ipfs.io/reference/http/api/ likely because they are scraping the individual commands which are not showing the global flags ipfs/kubo#6640.

Whether this gets fixed by manually changing things here or by resolving the linked go-ipfs issue is a matter of prioritization although I'd like to think at least documenting what's going manually is better than waiting on the coding fix here.

IMO we should put in some hard coded text for now and rip it out later.

Note: I'm not sure how we want to handle this in documentation but IIRC the global flags are not truly respected everywhere. e.g. this issue on --offline ipfs/kubo#6002.

cc @lidel since IIRC you're looking into a PR regarding other metadata changes to go-ipfs-cmds to help with documentation

[lidel]

My vote is to solve this in tools/http-api-docs: we should be able to programmatically read top-level flags (ones listed in ipfs --help) and use them to generate a new markdown section at the top of HTTP RPC API reference docs, before enumeration of specific commands.

If someone wants to contribute this, start by poking around tools/http-api-docs/endpoints.go to get metadata from the root of all commands, and then generate new markdown around formatter.go / markdown.go

[ElPaisano]

@lidel @aschmahmann triaging old issues:

I poked around https://docs.ipfs.io/reference/http/api/ and it looks like the flags called out here are still missing. We can document manually if need be, but it sounds like the automation is the best thing to focus on here. That being said, is this still relevant? Maybe the flags are in there now but I missed them? Thanks

[ElPaisano]

@lidel @aschmahmann re-flagging this (very old) issue. Can I get your thoughts? If this isn't relevant still, I can close.

[lidel]

This is still relevant, but also lower (P2?) priority.
Fwiw my pointers from #1084 (comment) are still valid if someone has time to pick this up.