cmake: Add rustdoc target

Add a target to the build `rustdoc` that will generate the rust
documentation.  The documentation will be placed in a target-specific
directory under `build/rust/target/...`.

There is some duplication in the cmake file, as I can't figure out how
to factor this out into a variable and maintain the proper quoting of
the space separated strings.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

CMakeLists.txt

@@ -143,6 +143,11 @@ WRAPPER_FILE = \"${WRAPPER_FILE}\"
 ${config_paths}
 ")
 
+  # The block of environment variables below could theoretically be captured in a variable, but this
+  # seems "challenging" in CMake (to be polite), as many of these contain spaces, and the quoting
+  # rules in CMake are inconsistent, at best.
+  # TODO: Figure out how to factor these out.
+
   # The library is built by invoking Cargo.
   add_custom_command(
     OUTPUT ${DUMMY_FILE}
@@ -183,6 +188,45 @@ ${config_paths}
         kobj_types_h_target
   )
 
+  # Command to generate the rust docs.  As mentioned above, the whole environment is duplicated, so
+  # it is important to keep this in sync with the above.
+  add_custom_command(
+    OUTPUT generate_rust_docs
+    COMMAND
+      ${CMAKE_COMMAND} -E
+      env BUILD_DIR=${CMAKE_CURRENT_BINARY_DIR}
+      ZEPHYR_BASE=${ZEPHYR_BASE}
+      DOTCONFIG=${DOTCONFIG}
+      ZEPHYR_DTS=${ZEPHYR_DTS}
+      INCLUDE_DIRS="${include_dirs}"
+      INCLUDE_DEFINES="${include_defines}"
+      WRAPPER_FILE="${WRAPPER_FILE}"
+      cargo doc
+      ${rust_build_type_arg}
+
+      # Override the features according to the shield given. For a general case,
+      # this will need to come from a variable or argument.
+      # TODO: This needs to be passed in.
+      # --no-default-features
+      # --features ${SHIELD_FEATURE}
+
+      # Set a replacement so that packages can just use `zephyr-sys` as a package
+      # name to find it.
+      ${command_paths}
+      --target ${RUST_TARGET}
+      --target-dir ${CARGO_TARGET_DIR}
+    COMMENT "Building Rust documentation"
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  )
+
+  add_custom_target(rustdoc
+    DEPENDS generate_rust_docs
+        # The variables, defined at the top level, don't seem to be accessible here.
+        syscall_list_h_target
+        driver_validation_h_target
+        kobj_types_h_target
+  )
+
   # Linking with the <rt_library> (`$<TARGET_PROPERTY:linker,rt_library>`).
   # -lgcc / -lcompiler_rt depending on toolchain, linker, and runtime library configuration.
   # In general this shouldn't be needed, as the runtime libary is generally linked late, but