Split docs to separate files by thaJeztah · Pull Request #506 · docker/buildx

thaJeztah · 2021-01-13T17:00:22Z

This moves the reference docs to the docs directory, splitting the readme to dedicated markdown files for each subcommand.

See individual commits for more details; with this change, #91 is able to include the extended descriptions and examples in the generated YAML docs, which are used for docs.docker.com; I opened a draft PR that updates the docs based on this pull request: docker/docs#12092; preview here; https://deploy-preview-12092--docsdocker.netlify.app/

thaJeztah · 2021-01-13T17:04:23Z

docs/reference/buildx.md

@@ -0,0 +1,32 @@
+# buildx


Note; moving the docs to be in docs/reference; this is more in line with other repositories that generate yaml docs (for integration in docs.docker.com); having these in a separate directory keeps the top docs/ directory available for other (non-reference) docs. If we don't anticipate other docs to be added, we could move to the top-level docs/

thaJeztah · 2021-01-13T17:05:12Z

README.md

@@ -159,697 +159,6 @@ Currently, the bake command supports building images from compose files, similar

 There is also support for custom build rules from HCL/JSON files allowing better code reuse and different target groups. The design of bake is in very early stages and we are looking for feedback from users.


Probably could move the "introduction" part to be included in the buildx top-level command, but can do that in a follow-up.

thaJeztah · 2021-01-13T17:05:51Z

README.md

-    + [`buildx bake [OPTIONS] [TARGET...]`](#buildx-bake-options-target)
-    + [`buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]`](#buildx-imagetools-create-options-source-source)
-    + [`buildx imagetools inspect NAME`](#buildx-imagetools-inspect-name)
+    + [`buildx build [OPTIONS] PATH | URL | -`](docs/reference/buildx_build.md)


Perhaps we should simplify these to be just buildx build (not listing the options/usage)

crazy-max · 2021-01-13T17:25:56Z

@thaJeztah That's really cool thanks for that! See also #504 about a recent change with the --progress flag for buildx build and buildx bake. Maybe add a note about that new env var?

thaJeztah · 2021-01-13T17:33:38Z

See also #504 about a recent change with the --progress flag for buildx build and buildx bake. Maybe add a note about that new env var?

Oh! Thanks for the link. We need to be a bit creative, because that option is not yet in the version of buildx that's currently shipping with Docker Desktop. I can create some follow-up PRs after this, and we can time merging those in the right order (so that I can generate the docs from master until these changes are in a release).

crazy-max · 2021-01-13T17:36:51Z

@thaJeztah Yes exactly not yet released, like you said a follow-up PR is a good move everytime the doc is impacted. Btw, there is also BUILDX_BUILDER to take into account.

tonistiigi · 2021-02-23T23:41:08Z

I think having the command outputs copy-pasted from the user's terminals is very error-prone. If we are going with this way then please add a script that generates them and validates that they are up-to-date in the CI. Should be easy to run buildx in a container or in a Dockerfile and copy outputs to the scratch stage.

I do think having separate pages affects the readability, especially in github where there is no sidebar. We should add extra links back to the TOC from a Documentation section in the page so if someone reads through the page they realize there is more context in the separate pages. If possible we could also consider adding markers to the main readme instead of separate pages to have the possibility to separate commands .

dieucao · 2021-02-24T02:38:46Z

Was chatting with @tonistiigi and I wondered if it might make sense to have a single page with multiple section links similar to how the Dockerfile reference is laid out at https://docs.docker.com/engine/reference/builder/ with section links along the right side, instead of splitting into multiple pages, as that seems a little closer to how it's laid out on the buildx Readme currently. @usha-mandya thoughts?

usha-mandya · 2021-02-24T19:08:54Z

Dieu, thanks for looping me in. I believe a separate page for each sub command makes sense as a single page with all the commands and their extended descriptions might increasing the page scroll. With a page each for the subcommands, readers will still be able to access other commands using the left nav. This is also inline with all other pages in the CLI reference section.

tonistiigi · 2021-03-23T18:22:47Z

Added generators from code and CI validation. Let's get this merged.

@thaJeztah Didn't make text changes. What's left is TOC visibility in the main readme and fix the titles of the flag definitions. These are not "examples" (that are not organized in any way so the only way to find information is to read through the whole page), but descriptions for the flags. Of course, flag descriptions can have examples and there can be general examples in a special section. If you need any more markers or yaml output, they can be added (probably in follow-up).

thaJeztah · 2021-03-24T14:30:59Z

docs/reference/buildx_build.md

+
+## Examples
+
+### <a name="platform"></a> Set the target platforms for the build (--platform)


Let me try updating my docs PR, and see if it likes this, or if it expects the "extended" syntax; https://www.markdownguide.org/extended-syntax/#heading-ids

Suggested change

### <a name="platform"></a> Set the target platforms for the build (--platform)

### Set the target platforms for the build (--platform) {#platform}

If they are functionally equivalent then we can use the markdown style. Need to update the generator as well as it is looking for HTML style marker atm. to see if link is possible.

Ok, I tried manually updating to the markdown syntax in docker/docs#12092 (preview at https://deploy-preview-12092--docsdocker.netlify.app/engine/reference/commandline/buildx_build/

So both work, but looks like the Markdown syntax works better, and is cleaner; in that case Jekyll accepts the custom ID; skipping its own generated one. So in that case there won't be two IDs (one custom and one generated);

Before:

After (with Markdown syntax):

I haven't tested what it looks like on GitHub though. Let's try if it works in this comment

Example with custom anchor-id {#mycustomid}

this is a link to the custom ID

Sigh... doesn't seem to work in GFM 😞 (I hate all the different flavours of markdown); https://github.github.com/gfm/

Let me dig a bit more to see if it's possible, otherwise we use the current approach

Looks like it's not possible with GitHub's markdown flavour, so let's keep the markdown as-is; perhaps I'll change the yamldocs generator to change it, but that's not for this PR

docs/reference/buildx_rm.md

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Use the usage output of `--help` for each subcommand, to make sure all flags/options are included on the page, and to make it easier to keep docs in sync. Note that the usage output is only used when reading these docs on GitHub; docs.docker.com only consumes the "description" and "example" sections (when present), and generates flag information and usage output from source Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Put the flag descriptions/examples under an "examples" section (used at docs.docker.com), and rephrase the headings to be more consistent with other pages in the docker documentation. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

thaJeztah

LGTM

thaJeztah · 2021-03-25T00:03:05Z

@tonistiigi I think this is good to merge (thanks for writing the generator code!); we can further improve after this

thaJeztah mentioned this pull request Jan 13, 2021

Update buildx reference docs docker/docs#12092

Merged

thaJeztah commented Jan 13, 2021

View reviewed changes

thaJeztah marked this pull request as ready for review January 13, 2021 18:59

tonistiigi force-pushed the split_docs branch 4 times, most recently from fe10ff1 to e16125c Compare March 23, 2021 18:10

thaJeztah commented Mar 24, 2021

View reviewed changes

docs/reference/buildx_rm.md Outdated Show resolved Hide resolved

thaJeztah and others added 9 commits March 25, 2021 00:37

docs: split reference docs to separate files

ff749d8

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs: add stubs for all commands

87ec3af

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs: fix markdown formatting and highlighting

17d4106

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs: add md generation

ca0f5da

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

docs: reference docs updates

c46407b

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

hack: add docs generation/validation

363c0fd

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

docs: add external docs links support

4047bcc

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

thaJeztah force-pushed the split_docs branch from e16125c to 4047bcc Compare March 24, 2021 23:46

thaJeztah commented Mar 25, 2021

View reviewed changes

tonistiigi merged commit 0147b92 into docker:master Mar 25, 2021

tonistiigi mentioned this pull request Mar 25, 2021

docs split follow-ups #571

Closed

thaJeztah deleted the split_docs branch March 25, 2021 08:45

crazy-max mentioned this pull request Jun 24, 2021

[WIP] Add YAML-docs generator #91

Closed

		@@ -159,697 +159,6 @@ Currently, the bake command supports building images from compose files, similar

		There is also support for custom build rules from HCL/JSON files allowing better code reuse and different target groups. The design of bake is in very early stages and we are looking for feedback from users.


		## Examples

		### <a name="platform"></a> Set the target platforms for the build (--platform)

	### <a name="platform"></a> Set the target platforms for the build (--platform)
	### Set the target platforms for the build (--platform) {#platform}

Conversation

thaJeztah commented Jan 13, 2021

Uh oh!

thaJeztah Jan 13, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jan 13, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jan 13, 2021

Choose a reason for hiding this comment

Uh oh!

crazy-max commented Jan 13, 2021

Uh oh!

thaJeztah commented Jan 13, 2021

Uh oh!

crazy-max commented Jan 13, 2021

Uh oh!

tonistiigi commented Feb 23, 2021

Uh oh!

dieucao commented Feb 24, 2021

Uh oh!

usha-mandya commented Feb 24, 2021

Uh oh!

tonistiigi commented Mar 23, 2021

Uh oh!

thaJeztah Mar 24, 2021

Choose a reason for hiding this comment

Uh oh!

tonistiigi Mar 24, 2021

Choose a reason for hiding this comment

Uh oh!

thaJeztah Mar 24, 2021

Choose a reason for hiding this comment

Example with custom anchor-id {#mycustomid}

Uh oh!

thaJeztah Mar 24, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Mar 25, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants