Merge pull request #801 from tweag/docs/improve-help-visualize

Improve documentation of visualise

CHANGELOG.md

@@ -53,6 +53,7 @@ This name should be decided amongst the team before the release.
 - [#794](https://github.com/tweag/topiary/pull/794) Bump the `tree-sitter` dependency to 0.24 @ZedThree
 - [#780](https://github.com/tweag/topiary/pull/780) Measuring scopes are now independent from captures order
 - [#790](https://github.com/tweag/topiary/pull/790) No longer merge config files by default, use priority instead.
+- [#801](https://github.com/tweag/topiary/pull/801) Improved documentation of the `visualise` subcommand
 
 ### Fixed
 - [#779](https://github.com/tweag/topiary/pull/779) Load relevant grammars before CLI tests

README.md

@@ -252,11 +252,20 @@ Note: `fmt` is a recognised alias of the `format` subcommand.
 
 #### Visualise
 
+`topiary visualise` converts the input's Tree-sitter parse tree to a graph
+representation in the selected format. By default, Topiary outputs a DOT file,
+which can be rendered using a visualisation tool such as the Graphviz suite. For
+example, using Graphviz's `dot`: `topiary visualise input.ocaml | dot -Tpng
+-ooutput.png`.
+
 <!-- DO NOT REMOVE THE "usage" COMMENTS -->
 <!-- usage:start:visualise -->
 ```
 Visualise the input's Tree-sitter parse tree
 
+Visualise generates a graph representation of the parse tree that can be rendered by external
+visualisation tools, such as Graphviz. By default, the output is in the DOT format.
+
 Usage: topiary visualise [OPTIONS] <--language <LANGUAGE>|FILE>
 
 Arguments:

topiary-cli/src/cli.rs

@@ -130,6 +130,10 @@ pub enum Commands {
     },
 
     /// Visualise the input's Tree-sitter parse tree
+    ///
+    /// Visualise generates a graph representation of the parse tree that can be rendered by
+    /// external visualisation tools, such as Graphviz. By default, the output is in the DOT
+    /// format.
     #[command(aliases = &["vis", "visualize", "view"], display_order = 2)]
     Visualise {
         /// Visualisation format