Improve documentation of visualise #801
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
Makes it clear, both in the README and in the command extended description, that visualise output raw graph data that needs to be rendered by an external tool, which wasn't entirely clear from the name of the command and the commend help message at first sight.
yannham
force-pushed
the
docs/improve-help-visualize
branch
from
fcb2b73 to
d2de2e7
Compare
nbacquey
approved these changes
Dec 5, 2024
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.
Improve visualise documentation
Context
I tried to use
topiary visualisefor the first time, and while the feature is cool, it took me a bit of time to understand how to get a final image that I could look at.The first detail is that given the command name and help message, I somehow expected (maybe naively in retrospective) that I would get some sort of direct visualisation, either as ASCII art or by generating an image directly.
The second issue was that the format of the output wasn't easy to find (DOT) so I didn't know what to do with the output (well, I somehow suspected it was DOT, but only because I happen to have worked with dot files a long time ago). Once again, in retrospective, I just had to look at the
--formatargument description, but I stopped at the extended description (which is the same as the short description) and expected to find information there.Description
This PR tries to make it clear, both in the README and in the command extended description, that visualise output raw graph data that needs to be rendered by an external tool, that the default format is DOT and that Graphviz is a recommended go-to solution for that.
Checklist
Checklist before merging: