docs: Add documentation generator info

docs/simulators.md

@@ -152,6 +152,40 @@ Now create the simulator program file `my-simulation.go`.
         // write your test code here
     }
 
+### Generating Test Case Documentation
+
+The [package hivesim] provides automatic test case generation that can be used to compile all the
+test cases that a given simulator runs into a markdown file.
+
+The documentation can be generated by executing the simulator binary with the environment variable
+`HIVE_DOCS_MODE` set to "true".
+
+The document generator recurses into every test suite and test function that the simulator defines
+and collects their names and descriptions, as defined in the `hivesim.Suite`, `hivesim.TestSpec`
+or `hivesim.ClientTestSpec` objects.
+
+If the test object contains no description, it will not be listed in the documentation generated.
+
+A `TESTS.md` file that serves as an index document will be generated, inside of it a listing of
+all the test suites will be included, along with the links to all test suite markdown files.
+
+For every test suite a `TESTS-<Suite Name>.md` file will be generated, containing the listing of
+all test cases included in the suite.
+
+The `Location` field of the `hivesim.Suite` can be used to specify a subdirectory where the 
+markdown file for this given suite will be placed.
+
+The `Category` field of `hivesim.TestSpec` or `hivesim.ClientTestSpec` can be used to generate
+test categories in which the test cases will be grouped for readability purposes.
+
+The following environment variables can be used to configure document generation:
+- `HIVE_DOCS_MODE`: Enable test case documentation generation (set to "true").
+- `HIVE_SIMULATOR_NAME`: Name of the simulator for which the documentation is being generated.
+If unset, the path of the simulator executable will be used to parse the simulator's name.
+- `HIVE_DOCS_OUTPUT_DIR`: Output root directory for all generated markdown files.
+If unset, the current working directory will be used.
+
+
 ### Creating the Dockerfile
 
 The simulator needs to have a Dockerfile in order to run.