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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.