Update documentation for command-line output options and custom reporters (#5335)

* Update documentation for command-line output options and custom reporters

* Make minor revisions to output documentation and new reporter example

* Improve output documentation spelling

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>

1 files changed, 39 insertions, 8 deletions

diff --git a/doc/user_guide/output.rst b/doc/user_guide/output.rst
index 4d375fdc7..52959d3c7 100644
--- a/doc/user_guide/output.rst
+++ b/doc/user_guide/output.rst
@@ -2,20 +2,51 @@
 Pylint output
 -------------
 
+Output options
+''''''''''''''''''''''''''''
+Output by default is written to stdout. The simplest way to output to a file is
+with the ``--output=<filename>`` option.
+
 The default format for the output is raw text. You can change this by passing
-pylint the ``--output-format=<value>`` option. Possible values are: json,
-parseable, colorized and msvs (visual studio).
+pylint the ``--output-format=<value>`` option. Possible values are: ``text``, ``json``,
+``parseable``, ``colorized`` and ``msvs`` (for Visual Studio).
 
 Multiple output formats can be used at the same time by passing
-``--output-format`` a comma-separated list of formats. To change the output file
-for an individual format, specify it after a semicolon. For example, you can
-save a json report to ``somefile`` and print a colorized report to stdout at the
-same time with :
+a comma-separated list of formats to ``--output-format``.
+This output can be redirected to a file by giving a filename after a colon.
+
+For example, to save a json report to ``somefile.json`` and print
+a colorized report to stdout at the same time:
+::
+
+  --output-format=json:somefile.json,colorized
+
+Finally, it is possible to invoke pylint programmatically with a
+reporter initialized with a custom stream:
+
 ::
 
-  --output-format=json:somefile,colorized
+  pylint_output = StringIO() # Custom open stream
+  reporter = text.TextReporter(pylint_output)
+  Run(["test_file.py"], reporter=reporter, do_exit=False)
+  print(pylint_output.getvalue()) # Retrieve and print the text report
+
+The reporter can accept any stream object as as parameter. In this example,
+the stream outputs to a file:
+
+::
+
+  with open("report.out", "w") as f:
+    reporter = text.TextReporter(f)
+    Run(["test_file.py"], reporter=reporter, do_exit=False)
+
+This would be useful to capture pylint output in an open stream which
+can be passed onto another program.
+
+Custom message formats
+''''''''''''''''''''''''''''
 
-Moreover you can customize the exact way information are displayed using the
+You can customize the exact way information are displayed using the
 `--msg-template=<format string>` option. The `format string` uses the
 `Python new format syntax`_ and the following fields are available :