Skip to content

.github: Add documentation workflow and Containerfile - #2114

Merged
gastmaier merged 3 commits into
mainfrom
staging/container-docs
Sep 22, 2026
Merged

.github: Add documentation workflow and Containerfile#2114
gastmaier merged 3 commits into
mainfrom
staging/container-docs

Conversation

@gastmaier

@gastmaier gastmaier commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

PR Description

Add documentation build on GitHub Actions

Adds full featured documentation builds to GitHub Actions, including building the IP cores with AMD Xilinx tools to generate the IP-XACT metadata.
The IP-XACT is used to verify and complete the documentation, for example, generate the IP block SVG, enrich the parameters and ports tables.

If AMD Xilinx tools are not available (detect by settings64.sh missing), gracefully skip building the libs.

Currently does not checkouts external dependencies, causing:

Library corundum_core SKIPPED due to missing external dependencies
Library ethernet_k26 SKIPPED due to missing external dependencies
Library ethernet_adrv9009zu11eg SKIPPED due to missing external dependencies
Library ethernet_vcu118 SKIPPED due to missing external dependencies
Library ethernet_xcvu11p SKIPPED due to missing external dependencies

Future improvements:

  • Libraries cache ; currently the action/checkout does 'git clean -xf .' internally (to save ~12m)
  • External dependencies

Solves: 'hidden' documentation builds.

PR Type

  • Bug fix (change that fixes an issue)
  • New feature (change that adds new functionality)
  • Breaking change (has dependencies in other repos or will cause CI to fail)
  • Documentation

PR Checklist

  • I have followed the code style guidelines
  • I have performed a self-review of changes
  • I have compiled all hdl projects and libraries affected by this PR
  • I have tested in hardware affected projects, at least on relevant boards
  • I have commented my code, at least hard-to-understand parts
  • I have signed off all commits from this PR
  • I have updated the documentation (wiki pages, ReadMe files, Copyright etc)
  • I have not introduced new Warnings/Critical Warnings on compilation
  • I have added new hdl testbenches or updated existing ones

github-actions Bot pushed a commit that referenced this pull request Jul 23, 2026
@cseci
deploy: dba8db0 #2114 (opened)
54ccf61 
https://analogdevicesinc.github.io/hdl/pull/2114
@gastmaier
gastmaier marked this pull request as ready for review July 23, 2026 16:07
github-actions Bot pushed a commit that referenced this pull request Sep 1, 2026
@cseci
deploy: f574155 #2114 (synchronize)
5514f91 
https://analogdevicesinc.github.io/hdl/pull/2114
@gastmaier

gastmaier commented Sep 21, 2026

Copy link
Copy Markdown
Contributor Author

@bia1708 with https://github.com/adi-innersource/ghdl/pull/379 merged, this should be merged too.

bia1708
bia1708 reviewed Sep 22, 2026
View reviewed changes
Comment thread .github/workflows/doc.yml Outdated
- uses: actions/checkout@v7
- name: Ensure SDKs
run: |
[[ -f "$SOURCE_AMD_XILINX" ]] && echo "vivado=true" >> $GITHUB_ENV || :

@bia1708 bia1708 Sep 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not fail this step if vivado isn't in the PATH and prevent it getting to the Build Libraries step?

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to keep it functional on fallback ubuntu-latest without any SDK, the documentation will be incomplete, but still builds. This way, forks of the repository remain functional.

Comment thread .github/workflows/doc.yml
github.event_name == 'pull_request' ||
github.ref_type == 'tag'

steps:

@bia1708 bia1708 Sep 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be skipped for PRs?

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image

We could preview docs, but let's not bloat the repo

Comment thread .github/workflows/doc.yml
Comment on lines +2 to +5
push:
branches:
- main
pull_request:

@bia1708 bia1708 Sep 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we build docs for PRs to any branch, shouldn't we also build them for pushes to release branches as well?

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will run on tag created instead of branch

@gastmaier
gastmaier force-pushed the staging/container-docs branch from 4070e13 to be81918 Compare September 22, 2026 09:10
gastmaier
gastmaier commented Sep 22, 2026
View reviewed changes

@gastmaier gastmaier left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

git diff 4070e13..be81918

Behavioral changes:

  • Deploy on tag
  • Don't deploy on pr
  • Warn on vendor sdk not available
  • docs/_build/html -> dirhtml

Kept fallback to ubuntu-latest and no vendor SDK to still build the doc

Comment thread .github/workflows/doc.yml
Comment on lines +2 to +5
push:
branches:
- main
pull_request:

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will run on tag created instead of branch

Comment thread .github/workflows/doc.yml Outdated
- uses: actions/checkout@v7
- name: Ensure SDKs
run: |
[[ -f "$SOURCE_AMD_XILINX" ]] && echo "vivado=true" >> $GITHUB_ENV || :

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to keep it functional on fallback ubuntu-latest without any SDK, the documentation will be incomplete, but still builds. This way, forks of the repository remain functional.

Comment thread .github/workflows/doc.yml
github.event_name == 'pull_request' ||
github.ref_type == 'tag'

steps:

@gastmaier gastmaier Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image

We could preview docs, but let's not bloat the repo

@gastmaier
.github/container: Add Containerfile
6d308ae 
Add minimal Containerfile with the dependencies for the SDK AMD Xilinx
(vitis, vivado).

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
@gastmaier
.github/doc: Add workflow to build doc
f4d771a 
If SOURCE_AMD_XILINX exists, source it and use to build the
libraries, since the component.xml IP-XACT data is used to verify the
documentation.

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
@gastmaier
docs/adrv9009: change zynqmp reference
87d173b 
The ZynqMP guides was split into multiple pages:

  - adrv9009 quickstart zynqmp
  + adrv9009 quickstart zcu102
  + adrv9009 quickstart zc706
  + adrv9009 quickstart kcu105
  + adrv9009 quickstart a10gx
  + adrv9009 quickstart a10soc

Link quickstart pages instead.

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
@gastmaier
gastmaier force-pushed the staging/container-docs branch from e873b7d to 87d173b Compare September 22, 2026 09:32
@gastmaier
gastmaier merged commit 0bf2f33 into main Sep 22, 2026
2 checks passed
@gastmaier
gastmaier deleted the staging/container-docs branch September 22, 2026 11:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@bia1708 bia1708 bia1708 approved these changes
@acostina acostina Awaiting requested review from acostina acostina is a code owner
@AndreiGrozav AndreiGrozav Awaiting requested review from AndreiGrozav AndreiGrozav is a code owner
@PopPaul2021 PopPaul2021 Awaiting requested review from PopPaul2021 PopPaul2021 is a code owner
@sarpadi sarpadi Awaiting requested review from sarpadi sarpadi is a code owner
@IuliaCMoldovan IuliaCMoldovan Awaiting requested review from IuliaCMoldovan IuliaCMoldovan is a code owner
@StancaPop StancaPop Awaiting requested review from StancaPop StancaPop is a code owner
@LBFFilho LBFFilho Awaiting requested review from LBFFilho LBFFilho is a code owner

Assignees

@bia1708 bia1708

@TudorAndreiTicudean TudorAndreiTicudean

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@gastmaier @bia1708 @TudorAndreiTicudean