flux-kvs(1): improve man page formatting #5588
Conversation
garlick
force-pushed
the
kvs_man_cleanup
branch
2 times, most recently
from
b76353b to
f416839
Compare
| @@ -38,7 +38,6 @@ DESCRIPTION | |||
| The Flux key-value store (KVS) is a simple, distributed data storage | |||
There was a problem hiding this comment.
commit message typo "copule" -> "couple"
doc/man1/flux-kvs.rst
Outdated
|
|
||
| Retrieve the value stored under *key* and print it on standard output. | ||
| It is an error if *key* does not exist, unless :option:``--waitcreate`` is | ||
| specified. It is an error if *key* is not a directory. |
doc/man1/flux-kvs.rst
Outdated
| With :option:`--watch`, display only the new data when the watched | ||
| is appended to. |
There was a problem hiding this comment.
"when the watched value is appended to"?
doc/man1/flux-kvs.rst
Outdated
| .. program:: flux kvs put | ||
|
|
||
| Set *key* to *value*. If *key* exists, the current value is overwritten. | ||
| If multiple *key=value* pairs are specified, they are send as one |
doc/man1/flux-kvs.rst
Outdated
| .. option:: -h, --help | ||
|
|
||
| Display help on this sub-command. | ||
|
|
||
| .. option:: -N, --namespace=NAME |
There was a problem hiding this comment.
personal preference ... --help option feels the least useful in the manpage (i.e. you're already in the manpage). List it last amongst all the options?
There was a problem hiding this comment.
Great point. Instead of repeating that option and the namespace one, I'll just mention them in the section intro.
doc/man1/flux-kvs.rst
Outdated
|
|
||
| .. option:: -A, --append | ||
|
|
||
| Append value(s) to key instead of overwriting. |
There was a problem hiding this comment.
no (s)? Or should be key(s)? I'd leave it singular.
doc/man1/flux-kvs.rst
Outdated
| Print the symbolic link target of *key*. The target may be another key name, | ||
| or a :option:`namespace::key` tuple. |
There was a problem hiding this comment.
similar to other sections above, say it's an error if key is not a link?
doc/man1/flux-kvs.rst
Outdated
| namespace remove | ||
| ---------------- | ||
|
|
||
| .. program:: flux kvs namespace remove | ||
|
|
||
| Remove a KVS namespace. | ||
|
|
||
| .. option:: -h, --help | ||
|
|
||
| Display help on this sub-command. |
There was a problem hiding this comment.
perhaps note that remove is done in the background? i.e. may not be removed when command returns.
garlick
force-pushed
the
kvs_man_cleanup
branch
from
f416839 to
1d36c51
Compare
|
Thanks @chu11, that was super helpful. I fixed those things and also reworded the last paragraph of the DESCRIPTION about namespaces, and added RFC 18 to the FLUX RFC section. |
Problem: the SYNOPSIS section of flux-kvs(1) doesn't list the subcommands so it's not very helpful. List all the sub-commands with commonly used options.
Problem: the flux-kvs(1) DESCRIPTION section uses outdated terminology and could use a bit of tidying up. Use "Flux instance" instead of "session". Capitalize KVS. Reword a couple of awkward sentences.
Problem: flux-kvs(1) sub-commands are not demarcated by document subsections, and the options for each sub-command are not properly formatted. Copy the structure of git-remote(1) and place subcommands in sub-sections of a COMMANDS section, with the subcommand name as the sub-section title in lower case. Declare the program name in each sub-section for x-ref, and define options properly so they are formatted in the HTML rendering like the other man pages. Option descriptions were altered to fit the new format, and reworded in some cases.
Problem: flux-kvs(1) includes commands that operate on RFC 18 eventlogs, without including the RFC in the FLUX RFC section. Add it.
garlick
force-pushed
the
kvs_man_cleanup
branch
from
3dfb053 to
a9346eb
Compare
Codecov Report
Additional details and impacted files@@ Coverage Diff @@
## master #5588 +/- ##
==========================================
- Coverage 83.43% 83.41% -0.03%
==========================================
Files 486 486
Lines 82456 82456
==========================================
- Hits 68796 68779 -17
- Misses 13660 13677 +17 |
Problem: flux-kvs(1) is hard to use as a reference.
Improve the synopsis, description, and break out sub-commands into sub-sections with properly declared options.