Add documentation for Rust support

.github/workflows/doc-build.yml

@@ -51,6 +51,7 @@ jobs:
           tests/
           **/Kconfig*
           west.yml
+          submanifests/optional.yaml
           scripts/dts/
           doc/requirements.txt
           .github/workflows/doc-build.yml
@@ -255,13 +256,93 @@ jobs:
           doc/_build/latex/zephyr.pdf
           doc/_build/latex/zephyr.log
 
+  rust-doc-build-html:
+    name: "Rust Documentation Build (HTML)"
+    needs: [doc-file-check]
+    if: >
+      github.repository_owner == 'zephyrproject-rtos' &&
+        ( needs.doc-file-check.outputs.file_check == 'true' || github.event_name != 'pull_request' )
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        path: zephyr
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+
+    - name: Setup Zephyr Project
+      uses: zephyrproject-rtos/action-zephyr-setup@v1
+      with:
+        app-path: zephyr
+        manifest-file-name: west.yml
+        toolchains: arm-zephyr-eabi
+
+    - name: Bring in docs
+      shell: bash
+      run: |
+        set -x
+        cd zephyr
+        # Show a git log to make sure we got the upstream version and west didn't "fix" it for us.
+        git log -3
+
+        # Add the rust module to the manifest.
+        west config manifest.project-filter +zephyr-lang-rust
+        west update zephyr-lang-rust
+
+        echo Rust support
+        ls -l ../modules/lang/rust
+
+    - name: Install Rust Target
+      shell: bash
+      run: |
+        rustup target add thumbv7em-none-eabi
+        rustup target add thumbv7m-none-eabi
+
+    - name: Build Rust docs
+      shell: bash
+      run: |
+        cargo --version
+        cd zephyr
+        west build -t rustdoc -b nrf52840dk/nrf52840 ../modules/lang/rust/docgen
+        cd ..
+        mkdir rustdocs
+        mv zephyr/build/rust/target/thumbv7em-none-eabi/doc rustdocs/nostd
+        cp modules/lang/rust/docs/top-index.html rustdocs/index.html
+
+    # TODO: Build the std-based docs as well
+    - name: Build Rust Build-time docs
+      shell: bash
+      run: |
+        cd modules/lang/rust/zephyr-build
+        cargo doc
+        mv target/doc ../../../../rustdocs/std
+
+        cd ../../../..
+        du -hs rustdocs
+        ls -l rustdocs
+
+    - name: compress-rust-docs
+      run: |
+        tar --use-compress-program="xz -T0" -cf rustdocs-output.tar.xz rustdocs
+
+    - name: Upload docs artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: rustdocs
+        path: rustdocs-output.tar.xz
+
   doc-build-status-check:
     if: always()
     name: "Documentation Build Status"
     needs:
     - doc-build-pdf
     - doc-file-check
     - doc-build-html
+    - rust-doc-build-html
     uses: ./.github/workflows/ready-to-merge.yml
     with:
       needs_context: ${{ toJson(needs) }}

.github/workflows/doc-publish-pr.yml

@@ -60,6 +60,9 @@ jobs:
         if [ -f api-coverage/api-coverage.tar.xz ]; then
           tar xf api-coverage/api-coverage.tar.xz -C api-coverage
         fi
+        if [ -f rustdocs/rustdocs-output.tar.xz ]; then
+          tar xf rustdocs/rustdocs-output.tar.xz -C rustdocs
+        fi
 
     - name: Configure AWS Credentials
       if: steps.download-artifacts.outputs.found_artifact == 'true'
@@ -82,3 +85,8 @@ jobs:
             s3://builds.zephyrproject.org/${{ github.event.repository.name }}/pr/${PR_NUM}/api-coverage \
             --delete
         fi
+        if [ -d rustdocs/rustdocs ]; then
+          aws s3 sync --quiet rustdocs/rustdocs/ \
+            s3://builds.zephyrproject.org/${{ github.event.repository.name }}/pr/${PR_NUM}/rustdocs \
+            --delete
+        fi

.github/workflows/doc-publish.yml

@@ -35,6 +35,9 @@ jobs:
         if [ -f api-coverage/api-coverage.tar.xz ]; then
           tar xf api-coverage/api-coverage.tar.xz -C api-coverage
         fi
+        if [ -f rustdocs/rustdocs-output.tar.xz ]; then
+          tar xf rustdocs/rustdocs-output.tar.xz -C rustdocs
+        fi
 
     - name: Configure AWS Credentials
       uses: aws-actions/configure-aws-credentials@v4
@@ -58,4 +61,7 @@ jobs:
         if [ -d api-coverage/coverage-report ]; then
           aws s3 sync --quiet api-coverage/coverage-report/ s3://docs.zephyrproject.org/api-coverage/${VERSION} --delete
         fi
+        if [ -d rustdocs/rustdocs ]; then
+          aws s3 sync --quiet rustdocs/rustdocs/ s3://docs.zephyrproject.org/rustdocs/${VERSION} --delete
+        fi
         aws s3 cp --quiet pdf-output/zephyr.pdf s3://docs.zephyrproject.org/${VERSION}/zephyr.pdf

doc/develop/languages/index.rst

@@ -8,3 +8,4 @@ Language Support
 
    c/index.rst
    cpp/index.rst
+   rust/index.rst

doc/develop/languages/rust/index.rst

@@ -0,0 +1,88 @@
+.. _language_rust:
+
+Rust Language Support
+#####################
+
+Rust is a modern systems programming language focused on safety, speed, and concurrency. Unlike
+traditional systems programming languages such as C and C++, Rust ensures memory safety without
+relying on garbage colleciton, thanks to its ownership model and borrow checker. Rust also offers a
+rich type system, expressive syntax, and support for zero-cost abstractions, making it well-suited
+for embedded development.
+
+Rust’s emphasis on reliability and performance aligns well with Zephyr. By combining Rust’s
+guarantees with Zephyr’s robust ecosystem, developers can create efficient and maintainable embedded
+applications. The integration of Rust with Zephyr allows developers to leverage Rust’s language
+features while benefiting from Zephyr’s drivers, APIs, and multi-threading capabilities.
+
+At this point, Rust support in Zephyr is entirely for those wishing to write applications in Rust
+that run *on* Zephyr.  Any efforts to add code *to* Zephyr, written in Rust (such as device drivers)
+would be an independent effort.
+
+Enabling Rust Support
+*********************
+
+Both Rust and Zephyr have their own build systems, along with an ecosystem around this.  For Rust,
+this is the "crate" system of managing external dependencies.  Because this support is for
+applications written in Rust, Zephyr's rust support leverages crates, and the cargo tool to build
+the Rust part of the application.
+
+Enabling the module
+-------------------
+
+Before getting very far, it is important to make sure that the Rust support module is included.  By
+default, rust support is listed in the project manifest, but is marked as optional.  It is easy to
+enable the module using ``west``:
+
+.. code-block:: console
+
+   west config manifest.project-filter +zephyr-lang-rust
+   west update
+
+This should enable the module, and then sync modules, which will add the module to your modules
+directory.
+
+Setting up the environment
+--------------------------
+
+Before starting with Rust, make sure you are able to build a simple Zephyr application, such as
+"blinky". It is easier to debug Zephyr build issues before introducing Rust.
+
+After this, you will need to have a recent Rust toolchain install, as well as target support for
+your desired target.  It is generally easiest to use `Rustup`_ to install an maintain a rust
+installation.  After following these instructions, you will need to install target support for your
+target.
+
+Because Zephyr and LLVM use different naming conventions for targets, and can be a little
+challenging to determine the right target to install.  Sometimes, it is easiest to proceed with
+building a Rust sample with your desired target, and the toolchain will emit an error message giving
+the appropriate command to run.  The target needed will depend both on the board/soc selected, as
+well as certain configuration choices (such as whether floating point is enabled).  Please see the
+function ``_rust_map_target`` in :module_file:`zephyr-lang-rust:CMakeLists.txt` for details on how
+this is computed.  As an example, a particular Cortex-M target may need the following command:
+
+.. code-block:: console
+
+   rustup target add thumbv7m-none-eabi
+
+.. _`Rustup`: https://rustup.rs/
+
+Building a sample
+-----------------
+
+.. This file (a directory in samples) and the above CMakeLists.txt should be done with the
+   module_file reference.  However, the current doc build doesn't seem to be including modules, so
+   for now, just make these regular file references.
+
+The directory :file:`zephyr-lang-rust:samples` contains some samples that can be useful for
+testing.  Hello world is a good basic test, although blinky may also be useful if your target has an
+LED defined.  Please make sure that :file:`samples/basic/blink` works with your board,
+however, before trying it with Rust.
+
+Following from the getting-started guide, you can build the hello world sample in rust with:
+
+.. code-block: console
+
+   cd ~/zephyrproject/modules/lang/rust
+   west build -p always -b <your-board-name> samples/blinky
+
+Provided this is successful, the image can be flashed and tested as per the getting started guide.