feat(build): add docs build step to build.zig & deploy docs job

[hendriknielaender]

Summary

This PR introduces two key improvements to our documentation workflow:

1. build.zig Enhancement

• Introduced a new build step (docs) to generate project documentation.

2. GitHub Actions Workflow

• Added .github/workflows/deploy-docs.yml.
• The workflow is triggered on every push to the master branch.
• Steps:
  • Checks out the code and sets up Zig.
  • Runs the new zig build docs step.
  • Uploads the generated documentation as a Pages artifact.
  • Deploys the artifact to GitHub Pages using the official actions/deploy-pages action.

Testing

• Verified that zig build docs produces the expected output locally.

Checklist

• Added docs build step to build.zig
• Added and tested GitHub Actions workflow
• Verified deployment to GitHub Pages

closes #52

[inge4pres]

What does this do?
Do we need it?

[hendriknielaender]

https://github.com/actions/deploy-pages?tab=readme-ov-file#security-considerations

url: ${{ steps.deployment.outputs.page_url }}
This sets the environment’s URL to the value of the page_url output from the deployment step.

[inge4pres]

Thanks for pointing me to the docs, I admit I am not entirely sure I understand what points 3 to 5 mean.
Do you think we should create an environment in the repo settings?
I don't have prior experience of deploying to GitHub pages 😄

[hendriknielaender]

I think that's not needed. Only gh pages needs to be enabled here.

[inge4pres]

Ok I did check the settings and pages are enabled.
Also the environment exists.

[inge4pres]

@hendriknielaender thanks for tackling this! ❤️
You seem to have added commits from a branch that have no diff (346480b to bbb6553).

They should go away if you git pull --rebase zig-o11y main in your local branch.

[hendriknielaender]

@hendriknielaender thanks for tackling this! ❤️ You seem to have added commits from a branch that have no diff (346480b to bbb6553).

They should go away if you git pull --rebase zig-o11y main in your local branch.

Oh yeah thank you 🙏 , missed that part. Didn't create the branch on a clean state.

[inge4pres]

Testing the CI part seems not possible, but the build part looks ok.

One thing I noticed when testing it: only the trace namespace pops up in the website 🤔

I will try and understand why.

If you want to see the website locally:

zig build docs
python -m http.server 8000 -d -out/docs/

[inge4pres]

Handy thread on Discord on how to setup the repo settings
https://discord.com/channels/605571803288698900/1194479404059996190

[inge4pres]

Little progress: I think the broader compilation is wrong, because the output of zig build is a static library with no symbols.
This means that, somehow, the current build config is not picking up the right artifacts.
For the sake of this PR, I am inclined to just approve and see if we publish the website correctly, then iterate further to understand what's wrong with the build in general.

☁  opentelemetry-sdk [build-docs] ⚡  readelf -s zig-out/lib/libopentelemetry-sdk.a

File: zig-out/lib/libopentelemetry-sdk.a(/home/francesco/Projects/github.com/zig-o11y/opentelemetry-sdk/.zig-cache/o/30646a4f6800f6a22ccd5611a0fe1ac7/libopentelemetry-sdk.a.o)

Symbol table '.symtab' contains 12 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
     0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND
     1: 0000000000000000     0 FILE    LOCAL  DEFAULT  ABS opentelemetry-sdk
     2: 0000000000000000     8 OBJECT  LOCAL  DEFAULT    3 builtin.zig_backend
     3: 0000000000000000     0 SECTION LOCAL  DEFAULT    3 .rodata.cst8
     4: 0000000000000000     1 OBJECT  LOCAL  DEFAULT    4 start.simplified[...]
     5: 0000000000000000     0 SECTION LOCAL  DEFAULT    4 .rodata
     6: 0000000000000001     1 OBJECT  LOCAL  DEFAULT    4 builtin.output_mode
     7: 0000000000000002     1 OBJECT  LOCAL  DEFAULT    4 builtin.link_mode
     8: 0000000000000000     0 SECTION LOCAL  DEFAULT    5 .debug_abbrev
     9: 0000000000000000     0 SECTION LOCAL  DEFAULT    6 .debug_info
    10: 0000000000000000     0 SECTION LOCAL  DEFAULT    8 .debug_str
    11: 0000000000000000     0 SECTION LOCAL  DEFAULT   14 .debug_line

[inge4pres]

Thanks for tackling this 🙏🏼

We have an unrelated problem with the build that prevents proper population of the docs, this PR works as intended and I'm looking forward to see it deployed after merging 👍🏼

[3052]

uh where is the result of this? where are the docs?