From: Chuck Lever <cel@kernel.org>
To: <kernel-tls-handshake@lists.linux.dev>
Cc: Xin Long <lucien.xin@gmail.com>, Chuck Lever <chuck.lever@oracle.com>
Subject: [PATCH v1 16/16] workflows: Generate gh-pages automatically
Date: Thu, 25 Sep 2025 21:22:05 -0400 [thread overview]
Message-ID: <20250926012207.3642990-17-cel@kernel.org> (raw)
In-Reply-To: <20250926012207.3642990-1-cel@kernel.org>
From: Chuck Lever <chuck.lever@oracle.com>
Add a GitHub Action that compiles the Doxygen comments and the man
pages in the tlshd source code and builds a .io web site. This is a
small step towards improving the published upstream documentation
for ktls-utils.
Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
.github/workflows/documentation.yml | 154 ++++++++++++++++++++++++++++
1 file changed, 154 insertions(+)
create mode 100644 .github/workflows/documentation.yml
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
new file mode 100644
index 000000000000..cf3425530261
--- /dev/null
+++ b/.github/workflows/documentation.yml
@@ -0,0 +1,154 @@
+---
+name: Generate public documentation
+
+on:
+ release:
+ types: [published]
+ workflow_dispatch:
+
+jobs:
+ generate-docs:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Cache dependencies
+ uses: actions/cache@v4
+ with:
+ path: |
+ /var/cache/apt
+ ~/.cache
+ key: ${{ runner.os }}-docs-${{ hashFiles('.github/workflows/documentation.yml') }}
+ restore-keys: |
+ ${{ runner.os }}-docs-
+
+ - name: Install build dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get -y install \
+ build-essential \
+ autoconf \
+ automake \
+ gnutls-dev \
+ libkeyutils-dev \
+ libnl-3-dev \
+ libnl-genl-3-dev \
+ libglib2.0-dev
+
+ - name: Install documentation tools
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y \
+ doxygen \
+ graphviz \
+ man2html
+
+ - name: Configure
+ run: |
+ ./autogen.sh
+ ./configure --with-systemd
+
+ - name: Generate HTML man pages
+ run: |
+ mkdir -p docs/man/html
+ if ! ls man/man* >/dev/null 2>&1; then
+ echo "No man page directories found, skipping HTML generation"
+ exit 0
+ fi
+ for section_dir in man/man*
+ do
+ if [ ! -d "$section_dir" ]; then
+ continue
+ fi
+ section_num=$(basename "$section_dir" | sed 's/man//')
+ echo "Processing section $section_num pages..."
+ find "$section_dir" -name "*.$section_num" -print0 | while IFS= read -r -d '' manpage; do
+ basename_file=$(basename "$manpage")
+ section=${basename_file##*.}
+ name=${basename_file%.*}
+ if ! man2html "$manpage" > "docs/man/html/${name}.${section}.html"; then
+ echo "Failed to convert $manpage"
+ exit 1
+ fi
+ done
+ done
+ ls -lR docs/man
+
+ - name: Generate Doxygen documentation
+ run: |
+ (cd docs && doxygen Doxyfile)
+
+ - name: Assemble final site
+ run: |
+ echo "::group::Assembling Documentation Site"
+
+ # Copy Doxygen HTML output
+ if [ -d docs/doxygen/html ]; then
+ cp -r docs/doxygen/html _site/
+ echo "✓ Doxygen HTML documentation copied"
+ else
+ echo "✗ No Doxygen HTML documentation found"
+ exit 1
+ fi
+
+ # Copy man page HTML and index
+ if [ -d docs/man/html ]; then
+ cp -r docs/man/html _site/
+ echo "✓ Manual page documentation copied"
+ else
+ echo "ℹ️ No manual pages to copy"
+ # Create empty man directory with placeholder
+ mkdir -p _site/man
+ cat > _site/man/index.html <<EOF
+ <!DOCTYPE html>
+ <html><head><title>Manual Pages</title></head>
+ <body>
+ <h1>Manual Pages</h1>
+ <p><a href="../index.html">← Back to Documentation Home</a></p>
+ <p><em>No manual pages available yet.</em></p>
+ </body></html>
+ EOF
+ fi
+
+ # Copy configuration examples
+ if [ -d docs/examples ]; then
+ cp -r docs/examples _site/
+ echo "✓ Configuration examples copied"
+ else
+ echo "ℹ️ No configuration examples to copy"
+ fi
+
+ # Add .nojekyll to disable Jekyll processing
+ touch _site/.nojekyll
+
+ # Create sitemap
+ find _site -name "*.html" | sed 's|_site/||' | while read file; do
+ echo "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/$file"
+ done > _site/sitemap.txt
+
+ echo "Documentation site assembled successfully"
+ echo "Total files: $(find _site -type f | wc -l)"
+ echo "Site size: $(du -sh _site | cut -f1)"
+
+ echo "::endgroup::"
+
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+
+ - name: Upload Pages artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: _site
+
+ - name: Deploy to GitHub Pages
+ if: github.ref == 'refs/heads/main'
+ id: deployment
+ uses: actions/deploy-pages@v4
--
2.51.0
prev parent reply other threads:[~2025-09-26 1:22 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-26 1:21 [PATCH v1 00/16] Create gh-pages for ktls-utils Chuck Lever
2025-09-26 1:21 ` [PATCH v1 01/16] tlshd: Add kernel's quic.h Chuck Lever
2025-09-26 1:21 ` [PATCH v1 02/16] tlshd: leave session_status as EIO on GnuTLS failure in QUIC session setup Chuck Lever
2025-09-26 1:21 ` [PATCH v1 03/16] tlshd: set conn errcode to EACCES on GnuTLS failure in QUIC handshake Chuck Lever
2025-09-26 1:21 ` [PATCH v1 04/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/client.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 05/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/config.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 06/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/handshake.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 07/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/keyring.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 08/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/ktls.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 09/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/log.c Chuck Lever
2025-09-26 1:21 ` [PATCH v1 10/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/main.c Chuck Lever
2025-09-26 1:22 ` [PATCH v1 11/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/netlink.c Chuck Lever
2025-09-26 1:22 ` [PATCH v1 12/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/quic.c Chuck Lever
2025-09-26 1:22 ` [PATCH v1 13/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/server.c Chuck Lever
2025-09-26 1:22 ` [PATCH v1 14/16] tlshd: Translate kernel-style Doxygen comments in src/tlshd/tlshd.h Chuck Lever
2025-09-26 1:22 ` [PATCH v1 15/16] Build Doxygen web site Chuck Lever
2025-09-26 1:22 ` Chuck Lever [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250926012207.3642990-17-cel@kernel.org \
--to=cel@kernel.org \
--cc=chuck.lever@oracle.com \
--cc=kernel-tls-handshake@lists.linux.dev \
--cc=lucien.xin@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox