diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..dc97c37f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,96 @@ +name: Generate and Preview Rust Docs + +on: + pull_request: + branches: + - main # Only generate docs for PRs targeting main + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +jobs: + generate-docs: + runs-on: ubuntu-24.04 + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + path: zephyr-lang-rust + + - 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-lang-rust + manifest-file-name: ci-manifest.yml + toolchains: arm-zephyr-eabi:riscv64-zephyr-elf + + - name: Install Rust Targets + shell: bash + run: | + rustup target add thumbv7em-none-eabi + rustup target add thumbv7m-none-eabi + + - name: Build Rust documentation + working-directory: zephyr-lang-rust + run: | + # Note that the above build doesn't set Zephyrbase, so we'll need to do that here. + west build -t rustdoc -b nrf52840dk/nrf52840 docgen + mkdir rustdocs + mv build/rust/target/thumbv7em-none-eabi/doc rustdocs/nostd + cp docs/top-index.html rustdocs/index.html + + - name: Build build documentation + working-directory: zephyr-lang-rust + run: | + cd zephyr-build + cargo doc + mv target/doc ../rustdocs/std + + - name: Upload docs artifact + uses: actions/upload-artifact@v4 + with: + name: rustdocs + path: zephyr-lang-rust/rustdocs + + doc-publish: + name: Publish Rust Documentation + needs: generate-docs + runs-on: ubuntu-24.04 + if: | + github.event_name == 'pull_request' && + github.repository == 'zephyrproject-rtos/zephyr-lang-rust' + + steps: + # - name: Show github context + # env: + # GITHUB_CONTEXT: ${{ toJson(github) }} + # run: | + # echo "$GITHUB_CONTEXT" | jq . + + - name: Download documentation artifact + uses: actions/download-artifact@v4 + with: + name: rustdocs + + # - name: Show our tree + # run: | + # find . -ls + + - name: Publish to S3 + env: + AWS_ACCESS_KEY_ID: ${{ vars.AWS_BUILDS_ZEPHYR_LANG_RUST_PR_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_BUILDS_ZEPHYR_LANG_RUST_PR_SECRET_ACCESS_KEY }} + AWS_REGION: us-east-1 + run: | + PR_NUM=${{ github.event.number || 'not-a-pr' }} + aws s3 sync --only-show-errors . s3://builds.zephyrproject.org/zephyr-lang-rust/pr/$PR_NUM/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 637e48ce..13a8bc43 100644 --- a/CMakeLists.txt +++ b/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 (`$`). # -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 diff --git a/docs/top-index.html b/docs/top-index.html new file mode 100644 index 00000000..3676efda --- /dev/null +++ b/docs/top-index.html @@ -0,0 +1,14 @@ + + + + + Documentation Index + + +

Documentation Index

+ + +