Generate YAML doc#747
Conversation
crazy-max
requested review from
thaJeztah and
tonistiigi
and removed request for
tonistiigi
thaJeztah
left a comment
thaJeztah
left a comment
There was a problem hiding this comment.
Thanks! Looks good.
The only thing we should discuss / look at / brainstorm is what the most practical location is for the generated yaml files. Does it work best if they're together in the same directory as the markdown files (what it currently does, i.e. /docs/reference/XXXX.yaml), or would it be more convenient to have them in their own directory (/docs/yaml/XXX.yaml (for example)).
Mostly thinking if the script at https://github.com/docker/docker.github.io/blob/master/_scripts/fetch-upstream-resources.sh would possibly need the markdown files to be put somewhere else, etc.
| github.com/serialx/hashring v0.0.0-20190422032157-8b2912629002 | ||
| github.com/sirupsen/logrus v1.8.1 | ||
| github.com/spf13/cobra v1.1.1 | ||
| github.com/spf13/cobra v1.2.1 |
There was a problem hiding this comment.
This was the (a) bit of the concern I had with not making it a submodule. (As it may unintentionally be "pushing" dependencies to newer versions).
The replace rules are a bit of a pain though, so I agree (at least for now) it's probably ok to keep it as-is.
Of course, we could (should) decide if we want these files to be fetched when building the docs, or to store a copy there (as we currently do); in both cases, we will need to look what's more practical (separate directory, or together) |
I think a flatten dir is ok to avoid maintenance cost if paths change in the future.
I think storing a copy on docker.github.io is better to track them as any other source code for reviews and so on. Also we should discuss about an auto repo sync like GitHub does on https://github.com/github/docs to be able to automatically create PR on changes. I think it would be great :)
About this line, as of Git 2.19, this is possible to clone a subdir with |
My train of thought was that "separate" would;
Again, just thoughts, so not strongly attached to one or the other, but thought I'd "brain dump" them here |
Signed-off-by: CrazyMax <[email protected]>
|
PTAL @thaJeztah @tonistiigi |
|
Why do we need to commit the generated yaml docs into the repo? |
|
@tonistiigi To be able to fetch them from the docs repo ( |
|
Can't the fetcher just generate them. I'm fine that we have a dockerfile target etc. here to run the generator and we can test it in this CI. But if the yaml itself is just an input to some external tool then I don't think we need to commit in copies for it. |
3 participants
Use cli-docs-tool to generate Markdown and now YAML docs.
@thaJeztah I have not used a sub gomod to avoid copy-pasting "require(...)" from the main one.
github.com/docker/cli-docs-toolwill not be used by./cmd/buildxas shown with the command below: