[Docs] Document scripts that are use to generate assertion in test cases

[xgupta]

Summary

This patch document llvm/utils/update_* python scripts that are used to generate
assertions in many of the LLVM regression test cases.

[xgupta]

correct heading

[RKSimon]

We have a number of similar update scripts (which you allude to), please can you list them with a basic description of their purposes:

update_analyze_test_checks.py
opt --analyze --costmodel

update_cc_test_checks.py
clang c/c++

update_llc_test_checks.py
llc

update_mca_test_checks.py
llvm-mca

update_mir_test_checks.py
llc mir checks

update_test_checks.py
opt

[xgupta]

This comment was removed by xgupta.

[xgupta]

mention similar update script

[MaskRay]

llvm/docs/TestingGuide.rst

290

Probably only run on existing tests which have the notice line.

Change build to something else to indicate it is a placeholder. Many people don't use build as the build directory.

294

This may render poorly in rst. Place them into a code-block

[jrtc27]

Suggested by @jrtc27

I didn't actually suggest doing this, just gave you example commands to run. I kind of take the view that everyone should be capable of reading the first line in the file marked NOTE: and working out how to run the script in question, it has a full --help output.

llvm/docs/TestingGuide.rst

290

Probably only run on existing tests which have the notice line.

That's what the -u is for, will check the NOTE: line exists and matches the script name

[jrtc27]

llvm/docs/TestingGuide.rst

285

290

Which means, if you're documenting things here, you should probably note what -u does, otherwise people writing new test files who come to run update_llc_test_checks.py -u might get rather confused as to why it's doing nothing...

298

C/C++, or clang/clang++

301

perhaps to distinguish from MIR, I know people (myself included) can get confused about the difference between update_llc and update_mir, but it's about the output being generated, not the input

307

[RKSimon]

llvm/docs/TestingGuide.rst

290

Its probably better to give an example that just specifies a couple of test files (e.g. 'test1.ll .... test3.ll' or something), trying to run the script on every file is slow and usually breaks somewhere that is then tricky to isolate.

292

I meant expand the brief descriptions that I put in the comment, but assuming this renders properly I guess its OK.

[xgupta]

address comments

[xgupta]

Thanks for the review.

llvm/docs/TestingGuide.rst

290

Change build to something else to indicate it is a placeholder. Many people don't use build as the build directory.

I have seen LLVM getting started and typofix tutorial, most llvm documents use build as standard, I also think it is better for copy-paste.

292

Probably do it some other day after using them a bit.

294

Thanks, I tested the generated .html file, it looks fine now.

[RKSimon]

LGTM (with one minor) - although I don't have a sphinx build around to check the formatting works.

Any other comments?

llvm/docs/TestingGuide.rst

302

C/C++, or clang/clang++ (IR checks)

[xgupta]

.

[xgupta]

I have attached the screenshot.

[RKSimon]

llvm/docs/TestingGuide.rst

294

"These are the most common scripts and their purposes/applications in generating assertions:"

[xgupta]

update

[MaskRay]

Thanks!

llvm/docs/TestingGuide.rst

291

292

[xgupta]

update

[jrtc27]

llvm/docs/TestingGuide.rst

298

I meant "change it to clang C/C++ or change it to clang/clang++", not "change it to a literal C/C++, or clang/clang++"

[xgupta]

llvm/docs/TestingGuide.rst

298

Maybe then I would have to say contributions are welcome to further improve/correct it.

llvm/docs/TestingGuide.rst

 The recommended way to examine output to figure out if the test passes is using
 the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN
 lines is deprecated - please do not send or commit patches that use it.]*
 
 Put related tests into a single file rather than having a separate file per
 test. Check if there are files already covering your feature and consider
 adding your code there instead of creating a new file.
 
+Generating assertions in regression tests
+-----------------------------------------
+
+Some regression test cases are very large and complex to write/update by hand.
+In that case to reduce the human work we can use the scripts available in
+llvm/utils/ to generate the assertions.
+
+For example to generate assertions in an :program:`llc`-based test, run:
+
+ .. code-block:: bash
+
+     % llvm/utils/update_llc_test_checks.py --llc-binary build/bin/llc test.ll
+
+And if you want to update assertions in an existing test case, pass `-u` option
+which first check the ``NOTE:`` line exists and matches the script name.
+
+These are the most common scripts and their purposes/applications in generating
+assertions:
+
+.. code-block::
+
+  update_analyze_test_checks.py
+  opt --analyze --costmodel
+
+  update_cc_test_checks.py
+  C/C++, or clang/clang++ (IR checks)
+
+  update_llc_test_checks.py
+  llc (assembly checks)
+
+  update_mca_test_checks.py
+  llvm-mca
+
+  update_mir_test_checks.py
+  llc (MIR checks)
+
+  update_test_checks.py
+  opt
+
 Extra files
 -----------
 
 If your test requires extra files besides the file containing the ``RUN:`` lines
 and the extra files are small, consider specifying them in the same file and
 using ``split-file`` to extract them. For example,
 
 .. code-block:: llvm