fix(rust): make rust doc tests not run with nightly (#364)

* fix(rust): make rust doc tests not run with nightly

* fix(docs): rust doc options

* fix(rust): Deny arithmetic side effects in the code (forces being thoughtful about overflow/underflow).

* fix(rust): Add llvm-tools-preview to the +nightly toolchain in case we want to use doctests with code coverage one day

* fix(rust): Run doctests serially, to prevent flaky builds from failed doctest compiles

* fix(rust): Don't enable arithmetic_side_effects = "deny" yet

* fix(rust): Use an env var to control rustdoc selectively only when building docs, not running doc tests

earthly/rust/Earthfile

@@ -407,7 +407,13 @@ INSTALL_RUST:
     RUN rustup component add llvm-tools-preview
 
     # Install a nightly toolchain which matches.
-    RUN rustup toolchain install nightly --component miri --component rust-src --component rustfmt --component clippy --component cargo
+    RUN rustup toolchain install nightly \
+        --component miri \
+        --component rust-src \
+        --component rustfmt \
+        --component clippy \
+        --component cargo \
+        --component llvm-tools-preview
 
     # Ensure we have all the necessary targets
     RUN rustup target add wasm32-unknown-unknown

earthly/rust/scripts/std_build.py

@@ -36,7 +36,7 @@ def cargo_lint(flags: str, verbose: bool = False) -> exec_manager.Result:
 
 def cargo_doctest(flags: str, verbose: bool = False) -> exec_manager.Result:
     return exec_manager.cli_run(
-        "cargo +nightly testdocs " + f"{flags} ",
+        "cargo testdocs " + f"{flags} ",
         name="Documentation tests all pass check",
         verbose=verbose,
     )
@@ -94,8 +94,13 @@ def cargo_bench(flags: str, verbose: bool = False) -> exec_manager.Result:
 
 
 def cargo_doc(verbose: bool = False) -> exec_manager.Result:
+    # Add RUSTDOCFLAGS to the inherited environment so we can build an index page with nightly.
+    env = os.environ
+    env["RUSTDOCFLAGS"] = "-Z unstable-options --enable-index-page"
     return exec_manager.cli_run(
-        "cargo +nightly docs ", name="Documentation build", verbose=verbose
+        "cargo +nightly docs", 
+        name="Documentation build", 
+        verbose=verbose
     )
 
 
@@ -328,9 +333,8 @@ def main():
         runner.run(cargo_lint, args.lint_flags, args.verbose)
 
         # Check if all Self contained tests pass (Test that need no external resources).
+        # But NOT doc tests, as these are not replacements for unit tests.
         if not args.disable_tests:
-            # Check if all documentation tests pass.
-            runner.run(cargo_doctest, args.doctest_flags, args.verbose)
             if args.cov_report == "":
                 # Without coverage report
                 runner.run(cargo_nextest, args.test_flags, args.verbose)
@@ -365,6 +369,15 @@ def main():
 
         results = runner.get_results()
 
+    # Check if all Self contained doc tests pass (Test that need no external resources).
+    # Can not be run in parallel with the normal builds as it becomes flaky and randomly fails.
+    # NOTE: DocTests are ONLY run to prove they are valid, they are NOT unit tests, and never
+    # currently contribute to code coverage.
+    if not args.disable_tests:
+        # Check if all documentation tests pass.
+        results.add(cargo_doctest(args.doctest_flags, args.verbose))
+
+
     results.print()
     if not results.ok():
         exit(1)

earthly/rust/stdcfgs/cargo_config.toml

@@ -27,11 +27,7 @@ rustflags = [
 
 [build]
 rustflags = []
-rustdocflags = [
-    "--enable-index-page",
-    "-Z",
-    "unstable-options",
-]
+rustdocflags = []
 
 [profile.dev]
 opt-level = 1

examples/rust/.cargo/config.toml

@@ -27,11 +27,7 @@ rustflags = [
 
 [build]
 rustflags = []
-rustdocflags = [
-    "--enable-index-page",
-    "-Z",
-    "unstable-options",
-]
+rustdocflags = []
 
 [profile.dev]
 opt-level = 1

examples/rust/Cargo.toml

@@ -44,4 +44,4 @@ panic = "deny"
 string_slice = "deny"
 unchecked_duration_subtraction = "deny"
 unreachable = "deny"
-missing_docs_in_private_items = "deny"
+missing_docs_in_private_items = "deny"

utilities/scripts/python/exec_manager.py

@@ -150,6 +150,7 @@ def cli_run(
     log: bool = True,
     timeout=None,
     verbose=False,
+    env=None
 ) -> Result:
     def procedure() -> ProcedureResult:
         result = subprocess.run(
@@ -159,6 +160,7 @@ def procedure() -> ProcedureResult:
             stderr=subprocess.STDOUT,
             text=True,
             timeout=timeout,
+            env=env
         )
         return ProcedureResult(result.returncode, command, result.stdout)