Automating config/API/CLI documentation

[johnnymatthews]

Note: This issue was opened as a result of the November 2019 close-reading audit captured in ipfs-inactive/docs#326.

This issue is one of the prioritized recommendations in the Q1 2020 IPFS Ecosystem Audit for execution in Q2/Q3 2020. Tagging it with $auditrecommendation means it's searchable! See all tagged issues in this repo.

In brief

Manually editing documentation that can be automated is an excellent way to create un-usable API docs and undocumented endpoints. Things get missed, misrepresented, and misunderstood. If we can find a way to automate the docs for all our APIs we can vastly improve the lives of IPFS devs and users.

What's needed

Find open-source, future-proof ways to (:anger: – biggest pain, easy to automate):

1. 💢 Automate the CLI docs (https://docs.ipfs.io/reference/cli/)
2. 💢 Figure out what best to do about HTTP API documentation (https://docs.ipfs.io/reference/http/api/)
3. 💢 Automate the go-ipfs config docs. (https://docs.ipfs.io/how-to/configure-node/)
   • either copy https://github.com/ipfs/go-ipfs/blob/master/docs/config.md or link to it
   • update: we talked about this during triage and decided to remove the copy of config.md and link to markdown with config docs in go-ipfs and js-ipfs repos instead (they diverged over time, no "universal" one anymore)
4. Automate the go-ipfs API docs. (https://docs.ipfs.io/reference/go/api)
5. Automate the js-ipfs API docs. (https://docs.ipfs.io/reference/js/api/ points at .md docs in js-ipfs repo)
6. Include those documentation automation tools into each project's build process, so every new version comes with a new set of docs.
7. Automatically pull in those docs into the primary IPFS docs repo and serve everything from one place using IPFS.

Deliverable

A report and roadmap for improving/automating API/CLI docs, including a platform decision (based on competitive analysis and best-in-breed research) and step-by-step timeline for implementation.

Additional notes/requirements

Note: These have been consolidated from a variety of legacy issues (#69, ipfs-inactive/docs#225, ipfs-inactive/docs#227, ipfs-inactive/docs#339, ipfs-inactive/docs#340) in order to reduce inefficiency.

• Solution must be open source.
• Solution must be hosted on IPFS (serverless). Per @Stebalien: "The rust docs implement client-side search that works pretty well."
• Currently, CLI command reference pages are generated from their respective repos and turned into .md files, but this process must (?) be manually triggered; what can be automated in this process? (Per @Stebalien: "'I'd like to be able to run make in this repo and regenerate all documentation, including the CLI documentation.)
• We don't have any useful approach to versioning right now. Our solution should. (Per @Stebalien: "it would also be great if we could update a single version number somewhere to update to a new go/js release.")
• HTTP API docs are specific to the go-ipfs implementation and fail to include anything unique to js-ipfs — and they don't explicitly note this.
• HTTP API docs are also "way too thin. All the in-depth docs in the Go code (where the HTTP docs are generated) can’t be used because they are very specific to the CLI and would be confusing for HTTP." Maintaining HTTP API docs separately (rather than generating from go-ipfs) would create a tool specific to the HTTPS use case, but will require a lot more effort to update, and requires more coordination between the Go and JS teams. (There's a longer discussion of this issue here that's worth reading when it's time to dig into this.)
• Folks are used to using Ctrl+F to find information in the existing (inefficient, large) list presentation we have now. Unless we give them something substantially better that's worth retraining their habits, we should preserve the usefulness of Ctrl+F.
• Every API resource/command section header should be a linkable anchor for purposes of easy sharing on forums, etc (per @lanzafame).
• Let's do our best from a UI perspective to display only the relevant information at the right time (to avoid information overload) while not breaking navigability, discoverability and search in the process.

[lidel]

I've marked low-hanging fruits with 💢 – those are go-ipfs specific things we could automate in a fashion similar to what we do in https://github.com/ipfs/npm-go-ipfs:

1. run every hour or day and detect when new go-ipfs release appears at https://github.com/ipfs/go-ipfs/releases
   • prior art: https://github.com/ipfs/npm-go-ipfs/blob/master/.github/workflows/main.yml
2. github workflow runs tools that generate updated docs based on the go-ipfs tag
   • http docs are produced by https://github.com/ipfs/http-api-docs based on go-ipfs sources
   • cli is just --help with some markdown, see - https://github.com/ipfs/ipfs-docs/tree/main/docs/reference
3. check if open/closed PR against docs.ipfs.io for specific docs and release exists, if not, open a new one with docs generated from sources in version tag
   • both cli and http api could be updated in the same PR

cc @aschmahmann @petar