Open RichardLitt opened 8 years ago
I would like to explain why I am proposing to use YAML. As those files will be modified by humans and we need pre-release processing done on them either way (as Go can't read pure data packages) we can use format that will be much nicer to edit.
A little comparison of YAML:
Name: dns
Options:
- Names: [ recursive, r ]
Type: bool
Description: Resolve until the result is not a DNS link.
Default: true # optional
Arguments:
- Name: domain-name
Type: string
Description: The domain-name name to resolve.
Required: true # optional defaults to true
Variadic: false # optional
Help:
Short: |
Multihashes are hard to remember, but domain names are usually easy to remember.
To create memorable aliases for multihashes, DNS TXT records can point to other DNS links, IPFS objects, IPNS keys, etc.
This command resolves those links to the referenced object.
Long: |
Long description here
4 spaces in the begging will be removed
vs JSON
{
"Name": "dns",
"Options": [
{
"Default": true,
"Type": "bool",
"Names": [
"recursive",
"r"
],
"Description": "Resolve until the result is not a DNS link."
}
],
"Arguments": [
{
"Description": "The domain-name name to resolve.",
"Required": true,
"Type": "string",
"Name": "domain-name",
"Variadic": false
}
],
"Help": {
"Short": "Multihashes are hard to remember, but domain names are usually easy to remember.\nTo create memorable aliases for multihashes, DNS TXT records can point to other DNS links, IPFS objects, IPNS keys, etc.\nThis command resolves those links to the referenced object.\n",
"Long": "Long description here\n4 spaces in the begging will be removed"
}
}
With the pre-release processing we can also give ourselves a bit more leeway on for example Name
vs Names
(just use Name
and allow it to be array or string).
Awesome! This will conveniently keep the help docs in sync. I'm personally a fan of JSON, but as Kuba mentioned, YAML can be really nice for editing +:
Can we kickstart this endeavour by extracting go-ipfs docs into a module, use them in js-ipfs, learn from the experience (try yaml and json) and then feed that into go-ipfs again?
I think it is great idea. I will work on the format but it would be best to just talk it through. Currently I am thinking about YAML file per command with subcommands in directories. Then we can build one uniform JSON from that.
Keys in objects can be small case, it doesn't matter for me.
Any idea for repo name?
I am also thinking about introducing more arguments types (go-ipfs currently uses: files and string) like: number, domain, multipath, multiaddr, multihash. Types could define fallback in case that given type is not handled by implementation (in case of go-ipfs it would be string for them most time).
Another thing: tests and linters, we should keep those documentation files as clean as possible, I know that right now I might be making the project much bigger than it should be but it will benefit us in a future.
Here is (I think) all data from go-ipfs in yaml: https://ipfs.io/ipfs/QmSty2WYzJ84chUVcSL8mLBi91ByKZ5ayo2EPxMWBwZnhq
There are some information missing but it should be solved on case by case basis.
I would encourage you to leave room to experiment for a while before settling on one final syntax.
Also :+1: for YAML. (see also HJSON, the more competent of the "human friendly JSON" things)
@Kubuxu
Oh, i just remembered, take a look at this, it seems pretty fantastic and has impls in the relevant langs:
I don't think that docopt will work for us as for simple number of commands we have.
Other thing is: For options I would like to allow overriding option arguments.
To explain:
-o FILE
- FILE
is option argument.
Can we start with this specification for each command, and add more as appropriate?
name: list # Natural language name
command: ipfs ls # Computational name (in path)
options:
- name: headers # Print headers, normally --headers
alias: v # Alias, can be also array
type: bool # Type of argument this option takes
default: true # Default
description: Show headers # Natural language description
arguments:
- name: ipfs-path
type: canonical-path # accepts also bare hash as /ipfs/HASH
required: true
variadic: true
description: The path to the IPFS object(s) to list links from.
help: # Output of the --help command
tagline: List links from an object. # Short description that is under 80 chars, generally
short: null # Description shown with -h
long: null # Full description
Sometimes we have more aliases, so I would allow alias
field to be both a string and array of strings. I would also like to come up with list of types.
We also have arguments and options so we need to account for that.
I will update above example.
Currently, go-ipfs has the most worked through, thorough, and generally solid documentation for the
ipfs
CLI app. However, js-ipfs also has a CLI. Rather than manually copying over all of the documentation in a long suite of PRs (as I've done before with, say, the http-api-spec or standard-readme implementation), it may be better to factor out the go-ipfs documentation into it's own module, and then import that into js-ipfs and go-ipfs.@Kubuxu has started some work on this, and has this json file which basically has all of the commands we'd need from go-ipfs. He suggested that we export docs, opts and args definitions from go-ipfs into YAML, and then rewrite synopsis generator to js and write converters.
What do we think about this? It would mean that the documentation isn't necessarily in the code - or, at least, it'll mean that we have to manually pull and push new versions each time something is fixed. But it should stop extra PRs happening for spelling errors and the like, and should help maintain documentation parity.