Merge pull request #301 from brodybits/improve-high-level-documentation

improve some high-level help text & documentation

README.rst

@@ -48,11 +48,17 @@ You can get started with a simple:
 
 This will by default run pytest (or unittest if pytest is unavailable)
 on tests in the "tests" or "test" folder and
-it will try to figure out where the code to mutate lies. Run
+it will try to figure out where the code to mutate lies.
+
+NOTE that mutmut will apply the mutations directly, one at a time;
+it is **highly** recommended to add all changes to source control
+before running.
+
+Enter
 
 .. code-block:: console
 
- mutmut --help
+ mutmut run --help
 
 for the available flags, to use other runners, etc. The recommended way to use
 mutmut if the defaults aren't working for you is to add a
@@ -96,11 +102,11 @@ grouped by file. You can now look at a specific mutant diff with ``mutmut show 3
 all mutants for a specific file with ``mutmut show path/to/file.py`` or all mutants
 with ``mutmut show all``.
 
-
 You can also write a mutant to disk with ``mutmut apply 3``. You should **REALLY**
 have the file you mutate under source code control and committed before you apply
 a mutant!
 
+To generate a HTML report for a web browser: ``mutmut html``
 
 Whitelisting
 ------------

mutmut/__init__.py

@@ -1286,7 +1286,7 @@ def compute_exit_code(
 ) -> int:
  """Compute an exit code for mutmut mutation testing
 
- The following exit codes are available for mutmut:
+ The following exit codes are available for mutmut (as documented for the CLI run command):
  * 0 if all mutants were killed (OK_KILLED)
  * 1 if a fatal error occurred
  * 2 if one or more mutants survived (BAD_SURVIVED)

mutmut/__main__.py

@@ -80,6 +80,16 @@ def do_apply(mutation_pk: str, dict_synonyms: List[str], backup: bool):
 def climain():
  """
  Mutation testing system for Python.
+
+ Getting started:
+
+ To run with pytest in test or tests folder: mutmut run
+
+ For more options: mutmut run --help
+
+ To show the results: mutmut results
+
+ To generate HTML report: mutmut html
  """
  pass
 
@@ -128,6 +138,29 @@ def run(argument, paths_to_mutate, disable_mutation_types, enable_mutation_types
  simple_output, no_progress, ci, rerun_all):
  """
  Runs mutmut. You probably want to start with just trying this. If you supply a mutation ID mutmut will check just this mutant.
+
+ Runs pytest by default (or unittest if pytest is unavailable) on tests in the “tests” or “test” folder.
+
+ It is recommended to configure any non-default options needed in setup.cfg or pyproject.toml, as described in the documentation.
+
+ Exit codes:
+
+ * 0 - all mutants were killed
+
+ Otherwise any or sum of any of the following exit codes:
+
+ * 1 - if a fatal error occurred
+
+ * 2 - if one or more mutants survived
+
+ * 4 - if one or more mutants timed out
+
+ * 8 - if one or more mutants caused tests to take twice as long
+
+ (This is equivalent to a bit-OR combination of the exit codes that may apply.)
+
+ With --CI flag enabled, the exit code will always be
+ 1 for a fatal error or 0 for any other case.
  """
  if test_time_base is None: # click sets the default=0.0 to None
  test_time_base = 0.0
@@ -255,7 +288,7 @@ def do_run(
 ) -> int:
  """return exit code, after performing an mutation test run.
 
- :return: the exit code from executing the mutation tests
+ :return: the exit code from executing the mutation tests for run command
  """
  if use_coverage and use_patch_file:
  raise click.BadArgumentUsage("You can't combine --use-coverage and --use-patch")