Move dockerd man page back from docker/cli #48298
Conversation
Prepare to move the dockerd man page back to this repository from docker/cli, retaining history. This partially reverts commit b5579a4. Signed-off-by: Cory Snider <csnider@mirantis.com>
This is a new option added specifically to allow for debugging of bugs in Docker's storage drivers or libdm itself. Signed-off-by: Aleksa Sarai <asarai@suse.de>
This builds (and depends) on moby#34087 Version 2: - remove --ipc argument validation (it is now done by daemon) - add/document 'none' value - docs/reference/run.md: add a table with better modes description - dockerd(8) typesetting fixes Version 3: - remove ipc mode tests from cli/command/container/opts_test.go Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Fix 19 typos, grammatical errors and duplicated words. These fixes have minimal impact on the code as these are either in the doc files or in comments inside the code files. Signed-off-by: Abdur Rehman <abdur_rehman@mentor.com>
Signed-off-by: Renaud Gaubert <renaud.gaubert@gmail.com>
- the `--disable-legacy-registry` daemon flag was removed - duplicate keys with conflicting values for engine labels now produce an error instead of a warning. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
…is separate commit for CLI files to address PR 36054 Signed-off-by: selansen <elango.siva@docker.com>
Signed-off-by: taiji-tech <csuhqg@foxmail.com>
update docs based on PR 39949 Signed-off-by: Lukas Heeren <lukas-heeren@hotmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Rob Gulewich <rgulewich@netflix.com>
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Anca Iordache <anca.iordache@docker.com>
This removes documentation related to legacy overlay networks using an external k/v store. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
…ocumentation This fix tries to address issues raised in moby#44346. The max-concurrent-downloads and max-concurrent-uploads limits are applied for the whole engine and not for each pull/push command. Signed-off-by: Luis Henrique Mulinari <luis.mulinari@gmail.com>
Signed-off-by: Ashly Mathew <ashlymathew93@gmail.com>
Adds documentation for the options that were added in moby@427c7cc Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
1. Escape asterisks and underscores, that have special meaning in Markdown. While most markdown processors are smart enough to distinguish whether it's a literal * or _ or a formatting directive, escaping makes things more explicit. 2. Fix using wrong level of headings in some dm options (most are ####, but some were #####). 3. Do not use sub-heading for examples in some dm options (this is how it's done in the rest of the man page). Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Mostly, this makes sure that literals (such as true, false, host, private, examples of options usage etc.) are typeset in bold, except for filenames, which are typeset in italic. While at it, - remove some default values from synopsis as it should not be there; - fix man pages references (page name in bold, volume number in regular). This is not a complete fix, but a step in the right direction. Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Signed-off-by: Grace Choi <gracechoi@utexas.edu> Signed-off-by: Pranjal Rai <pranjalrai@utexas.edu> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
|
I have opened this PR as a draft to kick off a conversation on how we want to integrate the man page into our build and CI tooling. We probably want CI to validate that the man page(s) can be generated from the markdown source without error, like is done in the docker/cli repo. What about the root Makefile? Do we want a target to build the man pages there? Should it be included in the |
| import ( | ||
| _ "github.com/cpuguy83/go-md2man/v2" | ||
| ) |
There was a problem hiding this comment.
We should have a look (in the CLI as well) if we can use the updated cli-docs-tools functionality to generate both the man-pages and the markdown variant for the daemon; in that case we may no longer need the separate md2man binary to produce the man-pages;
I think we should move both the man-page and the dockerd.md documentation back into this repository; the dockerd.md markdown documentation is currently 100% manually maintained, but with the cli-docs-tool can generate the "options" table with flag descriptions, combining it with manually maintained content from the markdown document; similar to https://github.com/docker/cli/blob/v27.1.1/docs/reference/commandline/container_run.md
There was a problem hiding this comment.
I gave it a shot and the results were not pretty. The auto-generated option descriptions are much more terse than those in the hand-written dockerd man page, which contains some multi-paragraph option descriptions that would be inappropriate for dockerd --help to output. And the ENVIRONMENT VARIABLES table that cli-docs-tools pulls in from dockerd.md when generating the man page is nearly unreadable on a terminal.
I don't think we should try to to generate the dockerd man page from Go sources at this time. It is too lossy.
Moving dockerd.md into this repository so that the options table can be kept up to date with auto-generated descriptions sounds reasonable. But it's orthogonal to this work. Could we do that work as a follow up to avoid boiling the ocean?
There was a problem hiding this comment.
Related to my other comment; if we generate, perhaps all of this should be part of cmd/dockerd (keeping all CLI-related code and content combined)?
There was a problem hiding this comment.
I'm not convinced it makes sense to split up the man pages by Go package/module. It would make things more awkward for packagers by forcing them to pull the man pages from multiple subtrees (if we document docker-proxy or add another command to this repo) vs. cp -R man/man*/* /usr/share/man/ when all the man pages are colocated. What are the upsides to counterbalance that?
422997f to
807c83e
Compare
man/Makefile
Outdated
| # Dynamically generate pattern rules for each manual section | ||
| # so make knows how to build a target like man8/dockerd.8. | ||
| define MANPAGE_template | ||
| man$(1)/%.$(1): %.$(1).md .build/go-md2man | man$(1) |
There was a problem hiding this comment.
How would you envision using this rule in places where there's already an appropriate go-md2man installed, such as in packaging (esp. where downloading/installing during build is inappropriate)? My cleanest answer given this code as-is would be to symlink the distribution-provided go-md2man binary into .build/go-md2man so this is satisfied or patching this Makefile directly to remove this dependency, but neither is exactly super great. 🤔
I guess the vendored dependencies you've included here help for my own personal builds, but won't help with getting this into the Debian builds, for example (since they'll have to strip vendor/), so I think it's still worth thinking about whether there's a better way we can enable using a pre-existing go-md2man here.
There was a problem hiding this comment.
Maybe a GO_MD2MAN variable or something that when set is used as the go-md2man implementation instead of building one? Then we'd do something like make GO_MD2MAN=go-md2man all and the Complicated Bits would live in the Makefile instead with an explicit signal-of-intent?
Vendor the go-md2man tool used to generate the man pages so that the only dependency is a Go toolchain. Signed-off-by: Cory Snider <csnider@mirantis.com>
Set the GO_MD2MAN make variable to elide building go-md2man from vendored sources and use the specified command instead. Signed-off-by: Cory Snider <csnider@mirantis.com>
807c83e to
edfde78
Compare
- What I did
Moved the dockerd man page back to this repo, with full history.
- How I did it
I made it self-contained by isolating the Go dependencies into a separate module and vendoring the tool sources. I put it all together with a clever Makefile.
I did not add any CI validation steps for man-page generation as it will not catch any issues with the Markdown sources.
go-md2manonly errors out if it encounters an I/O or path error.- How to verify it
From the repository root:
- Description for the changelog
- A picture of a cute animal (not mandatory but encouraged)