[Console] Improve markdown format #20866
Conversation
|
👍 To me it isn't a BC break, because the markdown format is not something meant to be analyzed programmatically and only intends to provide a quick documentation of the console application (I'm not even sure it'll be considered as a BC break for json actually, nor any format produced by a command is part of the BC promise). Status: Reviewed |
|
@ogizanagi I agree that this should't be considered a BC. By the way, a while ago I thought about opening a RFC issue to discuss about removing this feature. Do people really use this Markdown descriptor? |
|
It's nice API doc for a command. Ie. i would use this to generate a README.md for a command repo. |
|
I think it's an easy way to provide a minimalistic documentation for a tool and it is worth keeping it. I don't see as much utility for the json/xml descriptors though. I don't know what usages it deserves. Someone may try to implement a UI by parsing programmatically those formats, or maybe it can be consumed by generic worker in order to know which command to use and how to call it, but I never seen someone doing nor asking for this. |
|
Guys, before discussing removing something, you should assume that it was added for a reason :) The XML format is used by tools like IDEs to get information about available commands to provide a nice UI for instance. |
|
Yes, the XML export is useful for those cases. But what about the Markdown export? |
|
IIRC, the Markdown format has been added quite recently. So, let's dig a bit into the past PRs to see why it was added. |
|
This PR only tends to improve what we already have :) (application_2.md goes from 376 to 350 lines btw). |
|
What about removing |
|
Thank you @ro0NL. |
This PR was merged into the 3.3-dev branch. Discussion ---------- [Console] Improve markdown format | Q | A | ------------- | --- | Branch? | "master" | Bug fix? | no | New feature? | no | BC breaks? | not sure? | Deprecations? | no | Tests pass? | yes | Fixed tickets | comma-separated list of tickets fixed by the PR, if any | License | MIT | Doc PR | reference to the documentation PR, if any This improves the markdown description for a console application. To make the ouput read more friendly and intuitively (less bloated IMHO). Before: Markdown files in https://github.com/symfony/symfony/tree/master/src/Symfony/Component/Console/Tests/Fixtures After: Markdown files in https://github.com/ro0NL/symfony/tree/console/markdown/src/Symfony/Component/Console/Tests/Fixtures Commits ------- 302a19d [Console] Improve markdown format
|
I was late to this PR, but I was just about to propose the following improvements. This is how an app description looks like:
And here are some comments:
|
|
If the commands are hidden, I think they should not be part of the Mardown format but still be listed in the JSON or XML formats. The idea is that end users should not see them but machines should. 👍 for your other suggestions. |
…rs (ogizanagi) This PR was merged into the 3.3-dev branch. Discussion ---------- [Console] Show hidden commands in json & xml descriptors | Q | A | ------------- | --- | Branch? | master | Bug fix? | no (may be considered, but as hidden commands did not exist before 3.2, looks more like a behavior change, hence a feature) | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #20866 (comment) | License | MIT | Doc PR | N/A Commits ------- b6cf240 [Console] Show hidden commands in json & xml descriptors
…rs (ogizanagi) This PR was merged into the 3.3-dev branch. Discussion ---------- [Console] Show hidden commands in json & xml descriptors | Q | A | ------------- | --- | Branch? | master | Bug fix? | no (may be considered, but as hidden commands did not exist before 3.2, looks more like a behavior change, hence a feature) | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | symfony/symfony#20866 (comment) | License | MIT | Doc PR | N/A Commits ------- b6cf240ab5 [Console] Show hidden commands in json & xml descriptors
This improves the markdown description for a console application. To make the ouput read more friendly and intuitively (less bloated IMHO).
Before:
Markdown files in https://github.com/symfony/symfony/tree/master/src/Symfony/Component/Console/Tests/Fixtures
After:
Markdown files in https://github.com/ro0NL/symfony/tree/console/markdown/src/Symfony/Component/Console/Tests/Fixtures