Automate docs generation

mull-project · Dec 1, 2019 · f8acb09 · f8acb09
1 parent 2425533
commit f8acb09
Show file tree

Hide file tree

Showing 13 changed files with 572 additions and 21 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -199,3 +199,4 @@ add_subdirectory(tools)
 add_subdirectory(tests)
 add_subdirectory(vendor/googletest)
 add_subdirectory(vendor/libirm)
+add_subdirectory(docs)
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -0,0 +1,15 @@
+add_custom_target(generate-cli-options-doc
+  COMMAND $<TARGET_FILE:mull-cxx> --dump-cli > generated/CLIOptions.rst
+  DEPENDS mull-cxx
+  WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+)
+
+add_custom_target(generate-mutators-doc
+  COMMAND $<TARGET_FILE:mull-cxx> --dump-mutators > generated/Mutators.rst
+  DEPENDS mull-cxx
+  WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+)
+
+add_custom_target(build-docs
+  DEPENDS generate-mutators-doc generate-cli-options-doc
+)
diff --git a/docs/CommandLineReference.rst b/docs/CommandLineReference.rst
@@ -1,2 +1,4 @@
 Command Line Reference
-======================
+======================
+
+.. include:: generated/CLIOptions.rst
diff --git a/docs/SupportedMutations.rst b/docs/SupportedMutations.rst
@@ -1,2 +1,4 @@
 Supported Mutation Operators
-============================
+============================
+
+.. include:: generated/Mutators.rst
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,3 @@
+td p {
+  margin-right: 20px;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,8 +52,6 @@
 extensions.append("guzzle_sphinx_theme")
 html_theme = 'guzzle_sphinx_theme'
 
-# html_theme = 'pyramid'
-
 html_theme_options = {
     "project_nav_name": "Mull",
 }
@@ -63,4 +61,5 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = [ 'custom.css' ]
 master_doc = 'index'
diff --git a/docs/generated/CLIOptions.rst b/docs/generated/CLIOptions.rst
@@ -0,0 +1,168 @@
+--workers number		How many threads to use
+
+--dry-run		Skips real mutants execution. Disabled by default
+
+--cache-dir directory		Where to store cache (defaults to /tmp/mull-cache)
+
+--disable-cache		Disables cache (enabled by default)
+
+--report-name filename		Filename for the report (only for supported reporters). Defaults to <timestamp>.<extension>
+
+--report-dir directory		Where to store report (defaults to '.')
+
+--reporters reporter		Choose reporters:
+
+    :IDE:	Prints compiler-like warnings into stdout
+
+    :SQLite:	Saves results into an SQLite database
+
+    :Elements:	Generates mutation-testing-elements compatible JSON file
+
+--compdb-path filename		Path to a compilation database (compile_commands.json) for junk detection
+
+--compilation-flags string		Extra compilation flags for junk detection
+
+--ld-search-path directory		Library search path
+
+--include-path regex		File/directory paths to whitelist (supports regex)
+
+--exclude-path regex		File/directory paths to ignore (supports regex)
+
+--sandbox sandbox		Choose sandbox approach:
+
+    :None:	No sandboxing
+
+    :Watchdog:	Uses 4 processes, not recommended
+
+    :Timer:	Fastest, Recommended
+
+--test-framework framework		Choose test framework:
+
+    :GoogleTest:	Google Test Framework
+
+    :CustomTest:	Custom Test Framework
+
+    :SimpleTest:	Simple Test (For internal usage only)
+
+--mutators mutator		Choose mutators:
+
+    Groups:
+      :all:	cxx_all, experimental
+
+      :cxx_all:	cxx_assignment, cxx_increment, cxx_decrement, cxx_arithmetic, cxx_logical, cxx_comparison, cxx_boundary
+
+      :cxx_arithmetic:	cxx_minus_to_noop, cxx_add_to_sub, cxx_sub_to_add, cxx_mul_to_div, cxx_div_to_mul, cxx_rem_to_div
+
+      :cxx_arithmetic_assignment:	cxx_add_assign_to_sub_assign, cxx_sub_assign_to_add_assign, cxx_mul_assign_to_div_assign, cxx_div_assign_to_mul_assign, cxx_rem_assign_to_div_assign
+
+      :cxx_assignment:	cxx_bitwise_assignment, cxx_arithmetic_assignment, cxx_const_assignment
+
+      :cxx_bitwise:	cxx_bitwise_not_to_noop, cxx_and_to_or, cxx_or_to_and, cxx_xor_to_or, cxx_lshift_to_rshift, cxx_rshift_to_lshift
+
+      :cxx_bitwise_assignment:	cxx_and_assign_to_or_assign, cxx_or_assign_to_and_assign, cxx_xor_assign_to_or_assign, cxx_lshift_assign_to_rshift_assign, cxx_bitwise_rshift_assign_to_lshift_assign
+
+      :cxx_boundary:	cxx_le_to_lt, cxx_lt_to_le, cxx_ge_to_gt, cxx_gt_to_ge
+
+      :cxx_comparison:	cxx_eq_to_ne, cxx_ne_to_eq, cxx_le_to_gt, cxx_lt_to_ge, cxx_ge_to_lt, cxx_gt_to_le
+
+      :cxx_const_assignment:	cxx_assign_const, cxx_init_const
+
+      :cxx_decrement:	cxx_pre_dec_to_pre_inc, cxx_post_dec_to_post_inc
+
+      :cxx_default:	cxx_increment, cxx_arithmetic, cxx_comparison, cxx_boundary
+
+      :cxx_increment:	cxx_pre_inc_to_pre_dec, cxx_post_inc_to_post_dec
+
+      :cxx_logical:	cxx_logical_and_to_or, cxx_logical_or_to_and
+
+      :experimental:	negate_mutator, remove_void_function_mutator, scalar_value_mutator, replace_call_mutator
+
+    Single mutators:
+      :cxx_add_assign_to_sub_assign:	Replaces += with -=
+
+      :cxx_add_to_sub:	Replaces + with -
+
+      :cxx_and_assign_to_or_assign:	Replaces &= with \|=
+
+      :cxx_and_to_or:	Replaces & with |
+
+      :cxx_assign_const:	Replaces 'a = b' with 'a = 42'
+
+      :cxx_bitwise_not_to_noop:	Replaces ~x with x
+
+      :cxx_bitwise_rshift_assign_to_lshift_assign:	Replaces >>= with <<=
+
+      :cxx_div_assign_to_mul_assign:	Replaces /= with \*=
+
+      :cxx_div_to_mul:	Replaces / with *
+
+      :cxx_eq_to_ne:	Replaces == with !=
+
+      :cxx_ge_to_gt:	Replaces >= with >
+
+      :cxx_ge_to_lt:	Replaces >= with <
+
+      :cxx_gt_to_ge:	Replaces > with >=
+
+      :cxx_gt_to_le:	Replaces > with <=
+
+      :cxx_init_const:	Replaces 'T a = b' with 'T a = 42'
+
+      :cxx_le_to_gt:	Replaces <= with >
+
+      :cxx_le_to_lt:	Replaces <= with <
+
+      :cxx_logical_and_to_or:	Replaces && with ||
+
+      :cxx_logical_or_to_and:	Replaces || with &&
+
+      :cxx_lshift_assign_to_rshift_assign:	Replaces <<= with >>=
+
+      :cxx_lshift_to_rshift:	Replaces << with >>
+
+      :cxx_lt_to_ge:	Replaces < with >=
+
+      :cxx_lt_to_le:	Replaces < with <=
+
+      :cxx_minus_to_noop:	Replaces -x with x
+
+      :cxx_mul_assign_to_div_assign:	Replaces \*= with /=
+
+      :cxx_mul_to_div:	Replaces * with /
+
+      :cxx_ne_to_eq:	Replaces != with ==
+
+      :cxx_or_assign_to_and_assign:	Replaces \|= with &=
+
+      :cxx_or_to_and:	Replaces | with &
+
+      :cxx_post_dec_to_post_inc:	Replaces x-- with x++
+
+      :cxx_post_inc_to_post_dec:	Replaces x++ with x--
+
+      :cxx_pre_dec_to_pre_inc:	Replaces --x with ++x
+
+      :cxx_pre_inc_to_pre_dec:	Replaces ++x with --x
+
+      :cxx_rem_assign_to_div_assign:	Replaces %= with /=
+
+      :cxx_rem_to_div:	Replaces % with /
+
+      :cxx_rshift_to_lshift:	Replaces << with >>
+
+      :cxx_sub_assign_to_add_assign:	Replaces -= with +=
+
+      :cxx_sub_to_add:	Replaces - with +
+
+      :cxx_xor_assign_to_or_assign:	Replaces ^= with \|=
+
+      :cxx_xor_to_or:	Replaces ^ with |
+
+      :negate_mutator:	Negates conditionals !x to x and x to !x
+
+      :remove_void_function_mutator:	Removes calls to a function returning void
+
+      :replace_call_mutator:	Replaces call to a function with 42
+
+      :scalar_value_mutator:	Replaces zeros with 42, and non-zeros with 0
+
diff --git a/docs/generated/Mutators.rst b/docs/generated/Mutators.rst
@@ -0,0 +1,138 @@
+.. |op0| replace:: cxx_add_assign_to_sub_assign
+.. |desc0| replace:: Replaces += with -=
+.. |op1| replace:: cxx_add_to_sub
+.. |desc1| replace:: Replaces + with -
+.. |op2| replace:: cxx_and_assign_to_or_assign
+.. |desc2| replace:: Replaces &= with \|=
+.. |op3| replace:: cxx_and_to_or
+.. |desc3| replace:: Replaces & with |
+.. |op4| replace:: cxx_assign_const
+.. |desc4| replace:: Replaces 'a = b' with 'a = 42'
+.. |op5| replace:: cxx_bitwise_not_to_noop
+.. |desc5| replace:: Replaces ~x with x
+.. |op6| replace:: cxx_bitwise_rshift_assign_to_lshift_assign
+.. |desc6| replace:: Replaces >>= with <<=
+.. |op7| replace:: cxx_div_assign_to_mul_assign
+.. |desc7| replace:: Replaces /= with \*=
+.. |op8| replace:: cxx_div_to_mul
+.. |desc8| replace:: Replaces / with *
+.. |op9| replace:: cxx_eq_to_ne
+.. |desc9| replace:: Replaces == with !=
+.. |op10| replace:: cxx_ge_to_gt
+.. |desc10| replace:: Replaces >= with >
+.. |op11| replace:: cxx_ge_to_lt
+.. |desc11| replace:: Replaces >= with <
+.. |op12| replace:: cxx_gt_to_ge
+.. |desc12| replace:: Replaces > with >=
+.. |op13| replace:: cxx_gt_to_le
+.. |desc13| replace:: Replaces > with <=
+.. |op14| replace:: cxx_init_const
+.. |desc14| replace:: Replaces 'T a = b' with 'T a = 42'
+.. |op15| replace:: cxx_le_to_gt
+.. |desc15| replace:: Replaces <= with >
+.. |op16| replace:: cxx_le_to_lt
+.. |desc16| replace:: Replaces <= with <
+.. |op17| replace:: cxx_logical_and_to_or
+.. |desc17| replace:: Replaces && with ||
+.. |op18| replace:: cxx_logical_or_to_and
+.. |desc18| replace:: Replaces || with &&
+.. |op19| replace:: cxx_lshift_assign_to_rshift_assign
+.. |desc19| replace:: Replaces <<= with >>=
+.. |op20| replace:: cxx_lshift_to_rshift
+.. |desc20| replace:: Replaces << with >>
+.. |op21| replace:: cxx_lt_to_ge
+.. |desc21| replace:: Replaces < with >=
+.. |op22| replace:: cxx_lt_to_le
+.. |desc22| replace:: Replaces < with <=
+.. |op23| replace:: cxx_minus_to_noop
+.. |desc23| replace:: Replaces -x with x
+.. |op24| replace:: cxx_mul_assign_to_div_assign
+.. |desc24| replace:: Replaces \*= with /=
+.. |op25| replace:: cxx_mul_to_div
+.. |desc25| replace:: Replaces * with /
+.. |op26| replace:: cxx_ne_to_eq
+.. |desc26| replace:: Replaces != with ==
+.. |op27| replace:: cxx_or_assign_to_and_assign
+.. |desc27| replace:: Replaces \|= with &=
+.. |op28| replace:: cxx_or_to_and
+.. |desc28| replace:: Replaces | with &
+.. |op29| replace:: cxx_post_dec_to_post_inc
+.. |desc29| replace:: Replaces x-- with x++
+.. |op30| replace:: cxx_post_inc_to_post_dec
+.. |desc30| replace:: Replaces x++ with x--
+.. |op31| replace:: cxx_pre_dec_to_pre_inc
+.. |desc31| replace:: Replaces --x with ++x
+.. |op32| replace:: cxx_pre_inc_to_pre_dec
+.. |desc32| replace:: Replaces ++x with --x
+.. |op33| replace:: cxx_rem_assign_to_div_assign
+.. |desc33| replace:: Replaces %= with /=
+.. |op34| replace:: cxx_rem_to_div
+.. |desc34| replace:: Replaces % with /
+.. |op35| replace:: cxx_rshift_to_lshift
+.. |desc35| replace:: Replaces << with >>
+.. |op36| replace:: cxx_sub_assign_to_add_assign
+.. |desc36| replace:: Replaces -= with +=
+.. |op37| replace:: cxx_sub_to_add
+.. |desc37| replace:: Replaces - with +
+.. |op38| replace:: cxx_xor_assign_to_or_assign
+.. |desc38| replace:: Replaces ^= with \|=
+.. |op39| replace:: cxx_xor_to_or
+.. |desc39| replace:: Replaces ^ with |
+.. |op40| replace:: negate_mutator
+.. |desc40| replace:: Negates conditionals !x to x and x to !x
+.. |op41| replace:: remove_void_function_mutator
+.. |desc41| replace:: Removes calls to a function returning void
+.. |op42| replace:: replace_call_mutator
+.. |desc42| replace:: Replaces call to a function with 42
+.. |op43| replace:: scalar_value_mutator
+.. |desc43| replace:: Replaces zeros with 42, and non-zeros with 0
+
+
+============= ==================
+Operator Name Operator Semantics
+============= ==================
+|op0|         |desc0|
+|op1|         |desc1|
+|op2|         |desc2|
+|op3|         |desc3|
+|op4|         |desc4|
+|op5|         |desc5|
+|op6|         |desc6|
+|op7|         |desc7|
+|op8|         |desc8|
+|op9|         |desc9|
+|op10|        |desc10|
+|op11|        |desc11|
+|op12|        |desc12|
+|op13|        |desc13|
+|op14|        |desc14|
+|op15|        |desc15|
+|op16|        |desc16|
+|op17|        |desc17|
+|op18|        |desc18|
+|op19|        |desc19|
+|op20|        |desc20|
+|op21|        |desc21|
+|op22|        |desc22|
+|op23|        |desc23|
+|op24|        |desc24|
+|op25|        |desc25|
+|op26|        |desc26|
+|op27|        |desc27|
+|op28|        |desc28|
+|op29|        |desc29|
+|op30|        |desc30|
+|op31|        |desc31|
+|op32|        |desc32|
+|op33|        |desc33|
+|op34|        |desc34|
+|op35|        |desc35|
+|op36|        |desc36|
+|op37|        |desc37|
+|op38|        |desc38|
+|op39|        |desc39|
+|op40|        |desc40|
+|op41|        |desc41|
+|op42|        |desc42|
+|op43|        |desc43|
+============= ==================
diff --git a/include/mull/Mutators/MutatorsFactory.h b/include/mull/Mutators/MutatorsFactory.h
@@ -13,11 +13,13 @@ class MutatorsFactory {
 public:
   MutatorsFactory();
   std::vector<std::unique_ptr<Mutator>> mutators(const std::vector<std::string> &groups);
+  void init();
+  static std::string descriptionForGroup(const std::vector<std::string> &groupMembers);
   std::vector<std::pair<std::string, std::string>> commandLineOptions();
+  std::map<std::string, std::unique_ptr<Mutator>> &getMutatorsMapping();
+  std::map<std::string, std::vector<std::string>> &getGroupsMapping();
 
 private:
-  void init();
-
   std::map<std::string, std::unique_ptr<Mutator>> mutatorsMapping;
   std::map<std::string, std::vector<std::string>> groupsMapping;
 };