WIP: move command line reference docs for new command structure#26784
WIP: move command line reference docs for new command structure#26784
Conversation
Signed-off-by: Daniel Nephin <[email protected]>
|
cc @thaJeztah for sign-off on this approach |
|
hm, not sure. I originally was thinking of doing a Hugo redirect to the "canonical" command (and mention the aliases there). Let me ping @mstanleyjones as well for input |
|
That is another option that I was considering. I thought that it might be confusing to auto-redirect to a page that talks about a (slightly) command, but maybe not. |
|
This seems related but orthogonal to #26791. I don't have any particular opinion on the changes in this PR, but I wonder why we have all these aliases. I prefer this way than using Hugo redirects, as it creates more transparency for the reader. I can imagine some confusion if someone thinks they are going to one page and they get redirected to another with no explanation. |
Many of these docker commands were introduced when there were only two "object types": containers, and images. So they were all created as top level commands. Now we have volumes, networks, nodes, services, stacks, plugins, etc. All the new objects are under a "management subcommand" (ex We're trying to move all the older commands to match this same pattern, but we also don't want to break backwards compatibility. So for now they will remain as aliases. One day maybe we'll be able to deprecated them, and maybe some day after that they'll be long forgotten and we can actually remove them. |
mdlinville
left a comment
mdlinville
left a comment
There was a problem hiding this comment.
LGTM. Want to get this in before the Singularity tomorrow afternoon when we move docs into a separate repo?
|
It wont be ready in time for that this is just a preview of the much larger change I have to make. We also don't want to publish this until 1.13 is released, so there is plenty of time. |
|
@mstanleyjones all these changes are in the |
|
Oh, you are absolutely right. Disregard my prior comment. |
4 participants
Fixes: #26721
This is just a preview of the changes I'm going to make. I'd like to get this reviewed before I go moving everything. This is going to be a lot of manual work since we don't have #25615 yet.
For the man pages I would like to move the text into the command description so we can auto-generate the command. Since we had issues with in-lining the text I'll work on a way to store the description text in an external file that is just referenced from the source code.
If this looks correct, I'll proceed with the rest of the changes.