hivesim: dd documentation generation (#948)

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.

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/evanw/esbuild v0.18.11
 	github.com/fsouza/go-dockerclient v1.9.8
 	github.com/gorilla/mux v1.8.0
+	github.com/lithammer/dedent v1.1.0
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9
 	golang.org/x/net v0.17.0
 	gopkg.in/inconshreveable/log15.v2 v2.0.0-20200109203555-b30bc20e4fd1

go.sum

@@ -226,6 +226,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/labstack/echo/v4 v4.5.0/go.mod h1:czIriw4a0C1dFun+ObrXp7ok03xON0N1awStJ6ArI7Y=
 github.com/labstack/gommon v0.3.0/go.mod h1:MULnywXg0yavhxWKc+lOruYdAhDwPK9wf0OL7NoOu+k=
 github.com/leanovate/gopter v0.2.9 h1:fQjYxZaynp97ozCzfOyOuAGOU4aU/z37zf/tOujFk7c=
+github.com/lithammer/dedent v1.1.0 h1:VNzHMVCBNG1j0fh3OrsFRkVUwStdDArbgBWoPAffktY=
+github.com/lithammer/dedent v1.1.0/go.mod h1:jrXYCQtgg0nJiN+StA2KgR7w6CiQNv9Fd/Z9BP0jIOc=
 github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ=
 github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
 github.com/mattn/go-colorable v0.1.8/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=