[cli] config-help writes doc-compat output #1239
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This updates config-help to have more control over how the output is written for the user. We dump config-help output for per-generator documentation, and this cleans up some cross-platform compatibility issues that might arise from tweaking the output for clarity in the target file. Previously, we'd pipe config-help output to sed, then insert the generator name, which we then redirected to an output file. The sed syntax had to include a trailing newline so our tabbed configs would automatically become code tags in markdown. Inserting newlines into sed replacement strings doesn't work the same across platforms, mostly because of Apple's customizations to GNU programs. This commit moves the generator name and newline insertion into the command itself. It also includes a new --output option, allowing the user to specify the output location of the config-help. Currently, we only dump in plain-text, and it is only coincidental that our plaintext output results in a desirable Markdown output. If tabbed lines did not automatically convert to a code style block, some generators like C# would end up with broken text (`List<T>` would become just `List`, for example). I had previously discussed extending config-help to output to other formats like asciidoc. This commit does not introduce any steps toward that end.
wing328
added
Enhancement: Feature
Enhancement: General
and removed
Enhancement: Feature
labels
|
Looks good to me. (The shippable failure has been fixed in master) |
A-Joshi
pushed a commit
to ihsmarkitoss/openapi-generator
that referenced
this pull request
Feb 27, 2019
This updates config-help to have more control over how the output is written for the user. We dump config-help output for per-generator documentation, and this cleans up some cross-platform compatibility issues that might arise from tweaking the output for clarity in the target file. Previously, we'd pipe config-help output to sed, then insert the generator name, which we then redirected to an output file. The sed syntax had to include a trailing newline so our tabbed configs would automatically become code tags in markdown. Inserting newlines into sed replacement strings doesn't work the same across platforms, mostly because of Apple's customizations to GNU programs. This commit moves the generator name and newline insertion into the command itself. It also includes a new --output option, allowing the user to specify the output location of the config-help. Currently, we only dump in plain-text, and it is only coincidental that our plaintext output results in a desirable Markdown output. If tabbed lines did not automatically convert to a code style block, some generators like C# would end up with broken text (`List<T>` would become just `List`, for example). I had previously discussed extending config-help to output to other formats like asciidoc. This commit does not introduce any steps toward that end.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This updates config-help to have more control over how the output is
written for the user. We dump config-help output for per-generator
documentation, and this cleans up some cross-platform compatibility
issues that might arise from tweaking the output for clarity in the
target file.
Previously, we'd pipe config-help output to sed, then insert the
generator name, which we then redirected to an output file. The sed
syntax had to include a trailing newline so our tabbed configs would
automatically become code tags in markdown. Inserting newlines into sed
replacement strings doesn't work the same across platforms, mostly
because of Apple's customizations to GNU programs.
This commit moves the generator name and newline insertion into the
command itself. It also includes a new --output option, allowing the
user to specify the output location of the config-help.
Currently, we only dump in plain-text, and it is only coincidental that
our plaintext output results in a desirable Markdown output. If
tabbed lines did not automatically convert to a code style block, some
generators like C# would end up with broken text (
List<T>would becomejust
List, for example).I had previously discussed extending config-help to output to other
formats like asciidoc. This commit does not introduce any steps toward
that end.
PR checklist
./bin/to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.shand./bin/security/{LANG}-petstore.shif updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\.master,3.4.x,4.0.x. Default:master.Description of the PR
(details of the change, additional tests that have been done, reference to the issue for tracking, etc)