Skip to content

Commit 1e28a7b

Browse files
fdesbiensfdesbiens
authored
Added PDF manual generation for all Eclipse ThreadX components (#26)
Added PDF manual generation for all Eclipse ThreadX components This pull request introduces automated PDF manual generation for all 8 Eclipse ThreadX components (FileX, GUIX, LevelX, NetX Duo, ThreadX, ThreadX Modules, TraceX, USBX) in both A4 and US Letter formats, using antora/pdf-extension with asciidoctor-pdf as the converter. PDF build infrastructure - Added antora-pdf-playbook.yml: Antora playbook for PDF builds, registering @antora/pdf-extension for both A4 and US Letter output. - Added antora-assembler-pdf-a4.yml and antora-assembler-pdf-letter.yml: assembler configs with component filtering, assembly settings (book doctype, toc-placement: macro, section merge strategy), and build output to build/assembler/{a4,letter}/. - Added pdf/themes/: asciidoctor-pdf YAML themes with Eclipse ThreadX branding (navy #2C2255, blue #4DA8DA, Noto Sans/Noto Sans Mono fonts). - Added pdf/fonts/: Noto Sans and Noto Sans Mono TTF fonts (SIL OFL 1.1; Copyright 2022 The Noto Project Authors); OFL.txt and pdf/NOTICE.adoc included. - Added branding assets: eclipse-threadx-logo.png and eclipse-foundation-logo.png (Eclipse Foundation trademarks; NOTICE.adoc included); sourced from eclipse.org/artwork. - Added Gemfile: Ruby dependencies (asciidoctor-pdf, rouge, prawn-gmagick); prawn-gmagick enables full PNG/JPEG support including interlaced PNGs. - Added package.json: npm run build:html and npm run build:pdf scripts; Antora versions pinned to ^3.2.0-alpha.12. - Added .github/workflows/pdf-generate.yml: manual-trigger CI workflow (push trigger commented out pending creation of eclipse-threadx/rtos-docs-pdf). - Updated .gitignore: added node_modules/, package-lock.json, .bundle/, Gemfile.lock, build/. PDF quality features - Added rtos-docs/home/modules/ROOT/pages/pdf-legal.adoc: copyright and legal notice page (CC BY-SA 4.0, trademarks, contributing) inserted between the cover page and the table of contents in every manual; copyright year is resolved dynamically via {localyear}. - Added nav-pdf.adoc to all 8 components: flat navigation hierarchy that produces a page break before every chapter; excludes website-only links (home page, cross-component links, security advisories). - Added ext.assembler PDF profile to each component's antora.yml, pointing to nav-pdf.adoc. Copy script - Added scripts/copy-pdfs.js: collects all generated PDFs into a configurable output directory, renaming them to eclipse-threadx-<component>-<size>.pdf; supports --output <dir> flag and PDF_OUTPUT_DIR environment variable. - Added copy:pdf npm script. Content fixes - rtos-docs/guix/modules/ROOT/pages/chapter-3.adoc: removed orphaned passthrough markers around <widget_type>. - rtos-docs/netx-duo/modules/ROOT/pages/appendix-b.adoc: converted 1,471-line HTML passthrough table to native AsciiDoc (cols="1,1" table with 721 constant name-value pairs). - rtos-docs/usbx/modules/ROOT/pages/usbx-host-stack-3.adoc: added cols="1,2,1,1,6" to the USB endpoint descriptor table to prevent cell truncation in PDF output. - Re-encoded three TraceX JPEG assets that contained extraneous bytes before the EXIF marker. Documentation - Updated README.md: consolidated setup into a single section; instructions use npm run build:html / npm run build:pdf to ensure the locally pinned Antora version is used; added note that Ruby must be on PATH for PDF builds. Closes #11 Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com
1 parent 744cc1d commit 1e28a7b

49 files changed

Lines changed: 1806 additions & 1483 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pdf-generate.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Generate PDF Manuals
2+
3+
on:
4+
# Trigger manually only until the eclipse-threadx/rtos-docs-pdf output
5+
# repository has been created and PDF_REPO_TOKEN configured as a secret.
6+
# Add a 'push' trigger here once the destination repository is ready.
7+
workflow_dispatch:
8+
9+
jobs:
10+
generate-pdfs:
11+
name: Build and publish PDF manuals
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: read
15+
16+
steps:
17+
- name: Checkout documentation sources
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Checkout PDF output repository
23+
uses: actions/checkout@v4
24+
with:
25+
repository: eclipse-threadx/rtos-docs-pdf
26+
path: ../rtos-docs-pdf
27+
token: ${{ secrets.PDF_REPO_TOKEN }}
28+
29+
- name: Set up Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: '22'
33+
cache: 'npm'
34+
35+
- name: Set up Ruby
36+
uses: ruby/setup-ruby@v1
37+
with:
38+
ruby-version: '3.3'
39+
bundler-cache: true
40+
41+
- name: Install Node.js dependencies
42+
# The @antora/pdf-extension requires Antora >= 3.2 (testing channel).
43+
run: npm install @antora/cli@testing @antora/site-generator@testing @antora/pdf-extension
44+
45+
- name: Generate PDF manuals (A4 and US Letter)
46+
run: npx antora --fetch antora-pdf-playbook.yml
47+
48+
- name: Copy PDFs to output repository
49+
run: |
50+
mkdir -p ../rtos-docs-pdf/a4
51+
mkdir -p ../rtos-docs-pdf/letter
52+
cp build/assembler/a4/*.pdf ../rtos-docs-pdf/a4/ 2>/dev/null || echo "No A4 PDFs found"
53+
cp build/assembler/letter/*.pdf ../rtos-docs-pdf/letter/ 2>/dev/null || echo "No Letter PDFs found"
54+
55+
- name: Commit and push PDFs
56+
working-directory: ../rtos-docs-pdf
57+
run: |
58+
git config user.name "github-actions[bot]"
59+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
60+
git add -A
61+
if git diff --staged --quiet; then
62+
echo "No PDF changes to commit."
63+
else
64+
git commit -m "chore: regenerate PDF manuals [skip ci]
65+
66+
Generated from ${{ github.repository }}@${{ github.sha }}"
67+
git push
68+
fi

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,13 @@
11
__pycache__/
22
*.pyc
3+
4+
# Node.js
5+
node_modules/
6+
package-lock.json
7+
8+
# Ruby / Bundler
9+
.bundle/
10+
Gemfile.lock
11+
12+
# Antora build output
13+
build/

‎Gemfile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# frozen_string_literal: true
2+
3+
source 'https://rubygems.org'
4+
5+
gem 'asciidoctor-pdf'
6+
gem 'rouge'
7+
gem 'prawn-gmagick'
8+
9+
# Uncomment the following two gems if you are using Ruby >= 3.4,
10+
# where 'logger' and 'bigdecimal' were removed from the standard library.
11+
# gem 'logger'
12+
# gem 'bigdecimal'

‎README.md‎

Lines changed: 54 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,62 @@ This repository contains the AsciiDoc source for the [Eclipse ThreadX](https://t
44

55
If you want to propose changes or additions to the documentation, this is the right place!
66

7+
## Setup
8+
9+
The project uses specific pre-release versions of Antora. Always use the locally
10+
installed toolchain rather than any globally installed `antora`.
11+
12+
### Prerequisites
13+
14+
- Node.js 18+ with `npm`
15+
- Ruby 3.x with Bundler (`gem install bundler`), with Ruby on your `PATH`
16+
- [GraphicsMagick](http://www.graphicsmagick.org/) (required by `prawn-gmagick` for full image format support — needed for PDF generation only)
17+
18+
### Install dependencies
19+
20+
From the repository root:
21+
22+
```
23+
npm install
24+
bundle config --local path .bundle/gems && bundle install
25+
```
26+
727
## Generating the Website
828

9-
The documentation website is generated using [Antora](https://antora.org/). To build it locally:
10-
11-
1. Install Antora:
12-
```
13-
npm install -g @antora/cli @antora/site-generator
14-
```
15-
2. From the repository root, run:
16-
```
17-
antora antora-playbook.yml
18-
```
19-
3. The generated site will be output to the `../rtos-docs-html` directory.
29+
The documentation website is generated using [Antora](https://antora.org/).
30+
31+
```
32+
npm run build:html
33+
```
34+
35+
The generated site is written to `../rtos-docs-html`.
36+
37+
## Generating PDF Manuals
38+
39+
PDF manuals for all Eclipse ThreadX components are generated using the
40+
[Antora Assembler](https://docs.antora.org/assembler/latest/) (`@antora/pdf-extension`)
41+
with `asciidoctor-pdf` as the converter. Both A4 and US Letter formats are produced.
42+
43+
> **Note:** Ruby must be on your `PATH` before running the build command, as
44+
> Antora invokes `bundle exec asciidoctor-pdf` internally.
45+
46+
### Generate PDFs
47+
48+
```
49+
npm run build:pdf
50+
```
51+
52+
PDFs are written to `build/assembler/a4/` (A4) and `build/assembler/letter/` (US Letter),
53+
under `<component>/main/_exports/index.pdf`.
54+
55+
### Copy PDFs to a directory
56+
57+
To collect all PDFs into a single directory with descriptive filenames
58+
(e.g. `eclipse-threadx-threadx-a4.pdf`):
59+
60+
```
61+
node scripts/copy-pdfs.js --output /path/to/output/dir
62+
```
2063

2164
## What is Eclipse ThreadX?
2265

‎antora-assembler-pdf-a4.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Antora Assembler configuration for A4 PDF output.
2+
# See https://docs.antora.org/assembler/latest/ for full documentation.
3+
4+
component_version_filter:
5+
# Include all component versions except the 'home' landing page.
6+
names: ['*', '!home']
7+
8+
assembly:
9+
insert_start_page: false
10+
section_merge_strategy: discrete
11+
doctype: book
12+
attributes:
13+
toc: ''
14+
toc-placement: macro
15+
toc-title: Table of Contents
16+
toclevels: '3'
17+
secnums: ''
18+
xrefstyle: full
19+
source-highlighter: rouge
20+
rouge-style: github
21+
pdf-theme: ./pdf/themes/eclipse-threadx-pdf-theme-a4.yml
22+
# Eclipse ThreadX logo — placed in rtos-docs/home/modules/ROOT/assets/images/
23+
title-logo-image: 'image:home::eclipse-threadx-logo.png[pdfwidth=2in,align=center]'
24+
25+
build:
26+
dir: ./build/assembler/a4
27+
publish: false
28+
qualify_exports: true
29+
command: bundle exec asciidoctor-pdf

‎antora-assembler-pdf-letter.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Antora Assembler configuration for US Letter PDF output.
2+
# Inherits all settings from the A4 config; only the theme (page size) differs.
3+
# See https://docs.antora.org/assembler/latest/ for full documentation.
4+
5+
component_version_filter:
6+
names: ['*', '!home']
7+
8+
assembly:
9+
insert_start_page: false
10+
section_merge_strategy: discrete
11+
doctype: book
12+
attributes:
13+
toc: ''
14+
toc-placement: macro
15+
toc-title: Table of Contents
16+
toclevels: '3'
17+
secnums: ''
18+
xrefstyle: full
19+
source-highlighter: rouge
20+
rouge-style: github
21+
pdf-theme: ./pdf/themes/eclipse-threadx-pdf-theme-letter.yml
22+
# Eclipse ThreadX logo — placed in rtos-docs/home/modules/ROOT/assets/images/
23+
title-logo-image: 'image:home::eclipse-threadx-logo.png[pdfwidth=2in,align=center]'
24+
25+
build:
26+
dir: ./build/assembler/letter
27+
publish: false
28+
qualify_exports: true
29+
command: bundle exec asciidoctor-pdf

‎antora-pdf-playbook.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
site:
2+
title: Eclipse ThreadX Documentation
3+
url: https://threadx.io
4+
start_page: home::index.adoc
5+
6+
content:
7+
sources:
8+
- url: .
9+
branches: HEAD
10+
start_paths:
11+
- rtos-docs/filex
12+
- rtos-docs/home
13+
- rtos-docs/guix
14+
- rtos-docs/levelx
15+
- rtos-docs/netx-duo
16+
- rtos-docs/threadx
17+
- rtos-docs/threadx-modules
18+
- rtos-docs/tracex
19+
- rtos-docs/usbx
20+
21+
ui:
22+
bundle:
23+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
24+
snapshot: true
25+
26+
# Skip HTML site publishing — this playbook is for PDF generation only.
27+
output:
28+
destinations: []
29+
30+
antora:
31+
extensions:
32+
- require: '@antora/pdf-extension'
33+
config_file: antora-assembler-pdf-a4.yml
34+
- require: '@antora/pdf-extension'
35+
config_file: antora-assembler-pdf-letter.yml

‎log.txt‎

-1.02 MB
Binary file not shown.

‎package.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "eclipse-threadx-docs",
3+
"private": true,
4+
"description": "Eclipse ThreadX AsciiDoc documentation sources",
5+
"scripts": {
6+
"build:html": "antora --fetch antora-playbook.yml",
7+
"build:pdf": "antora --fetch antora-pdf-playbook.yml",
8+
"copy:pdf": "node scripts/copy-pdfs.js"
9+
},
10+
"dependencies": {
11+
"@antora/cli": "^3.2.0-alpha.12",
12+
"@antora/pdf-extension": "^1.0.0-beta.20",
13+
"@antora/site-generator": "^3.2.0-alpha.12"
14+
}
15+
}

‎pdf/NOTICE.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
= Third-Party Notices — PDF Generation Assets
2+
3+
This file provides copyright notices and license information for all
4+
third-party assets used when generating the Eclipse ThreadX PDF manuals.
5+
6+
== Eclipse ThreadX Logo
7+
8+
The Eclipse ThreadX logo is the intellectual property of the Eclipse Foundation
9+
and is provided under the
10+
https://www.eclipse.org/legal/logo_guidelines.php[Eclipse Foundation Trademark
11+
Usage Policy]. These logos may not be altered without the Eclipse Foundation's
12+
permission.
13+
14+
Copyright (c) Eclipse Foundation. All Rights Reserved.
15+
16+
Source: https://www.eclipse.org/org/artwork/zip-files/threadx-logo.zip
17+
18+
== Eclipse Foundation Logo
19+
20+
The Eclipse Foundation logo is the intellectual property of the Eclipse
21+
Foundation and is provided under the
22+
https://www.eclipse.org/legal/logo_guidelines.php[Eclipse Foundation Trademark
23+
Usage Policy]. These logos may not be altered without the Eclipse Foundation's
24+
permission.
25+
26+
Copyright (c) Eclipse Foundation. All Rights Reserved.
27+
28+
Source: https://www.eclipse.org/org/artwork/zip-files/eclipse-foundation-logo.zip
29+
30+
== Noto Sans and Noto Sans Mono Fonts
31+
32+
The Noto Sans and Noto Sans Mono fonts are used as the body, heading, and code
33+
typefaces in the generated PDF manuals.
34+
35+
Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
36+
37+
These fonts are licensed under the
38+
https://scripts.sil.org/OFL[SIL Open Font License, Version 1.1].
39+
The full license text is provided in `pdf/fonts/OFL.txt`.
40+
41+
Source: https://github.com/notofonts/notofonts.github.io

0 commit comments

Comments
 (0)