Add the wolfTPM manual as an in-repo docs/ source with build tooling

[aidangarske]

Add the wolfTPM manual as an in-repo docs source with build tooling

• The manual lived only in the wolfSSL/documentation website repo, was outdated (the build-options list predated fwTPM,
  post-quantum, SPDM, and SealSQ), and every change needed a PR against a separate repo.
• Adds the manual under docs/ as the single source of truth: 34 English pages plus a full Japanese mirror under docs/ja/,
  following the merged wolfCOSE pattern.
• Adds the build tooling: the tools/docs_manual.py adapter, tools/docs-manual/, the docker/docs builder image, mkdocs.yml and
  mkdocs-ja.yml, and the docs-site.yml and publish-docs-image.yml workflows.
• Keeps the Doxygen API reference auto-generated with doxygen and doxybook2 and injects it at build time for both languages.
• Reworks README.md into a landing page and leaves docs/FWTPM.md, SWTPM.md, DEVTPM.md, and WindowTBS.md as redirect stubs to the
  website manual.
• The website side that points the build at this docs tree is a separate PR against wolfSSL/documentation.

Manual and Docs structure

docs/ (English manual; docs/ja/ is a full Japanese mirror of every page)

Overview
├── index.md .................. landing page: what wolfTPM is, feature matrix, standards table, doc map
├── tpm2-overview.md .......... TPM 2.0 concepts: hierarchies, PCRs, sessions, device identification
└── project-structure.md ...... source-tree layout and where each component lives

Getting Started
├── getting-started.md ........ install, build, run your first example
├── building.md ............... autotools and CMake builds, out-of-tree wolfSSL, bare-metal
├── build-options.md .......... every --enable/--disable flag and WOLFTPM_* macro, grouped by theme
└── system-interfaces.md ...... software simulator (SWTPM), Linux /dev/tpmX, Windows TBS

Hardware
├── supported-hardware.md ..... per-part sections (Infineon, ST, Microchip, Nuvoton, Nations, SealSQ) with build + wiring
└── hal-io-callback.md ........ the single IO-callback porting model and wolfHAL

Usage
├── examples-overview.md ...... map of the example programs and how to run them
├── key-management.md ......... keygen and key loading (RSA/ECC/symmetric, primary/child)
├── attestation.md ............ PCR quote, make/activate credential, endorsement, timestamp, device identity
├── sealing-and-nvram.md ...... sealing/unsealing and NV storage, counters, secure boot
├── tls-and-certificates.md ... CSR, PKCS7, TLS client/server with a TPM-held key
├── firmware-update.md ........ ST33 and Infineon firmware update flow
└── management-and-gpio.md .... TPM management commands and GPIO configure/read/write

Post-Quantum
└── post-quantum.md ........... ML-DSA and ML-KEM (v1.85), build flags, PQC examples, PQC TLS 1.3, SealSQ QVault

SPDM
└── spdm.md ................... SPDM secure sessions over the TCG binding: identity and PSK modes, SPDM-only lock, vendor commands

Firmware TPM (docs/fwtpm/ — self-contained sub-manual)
├── overview.md ............... the wolfCrypt firmware TPM: what it is, command coverage, architecture, positioning
├── building.md ............... fwTPM build flags, defines, feature gates, size tuning
├── usage.md .................. running fwtpm_server, client connect, socket and TIS/SHM transports, NV persistence
├── hal-and-porting.md ........ the IO and NV HAL callbacks and porting to a board
├── post-quantum.md ........... PQC on the firmware TPM (the eight v1.85 commands in software)
└── spdm.md ................... the fwTPM SPDM 1.3 responder for testing without silicon

Wrappers
├── rust-wrapper.md ........... the Rust wrapper crate
└── csharp-wrapper.md ......... the C# wrapper

Integrations
├── stm32cube.md .............. STM32CubeMX/CubeIDE integration
└── embedded-integrations.md .. Espressif, Zephyr, QNX, IAR, Visual Studio, U-Boot, Xilinx

Reference
├── api-reference.md .......... thin orientation (wrapper vs native API), then the generated Doxygen pages
├── testing.md ................ how to run the tests and an overview of the CI workflows
├── benchmarks.md ............. compiled benchmark numbers per part and the SealSQ PQC figures
├── sbom-and-compliance.md .... SBOM generation (CycloneDX/SPDX) and EU CRA notes
├── release-notes.md .......... release history
└── cited-sources.md .......... spec and reference links (TCG, FIPS, RFCs)

Reference / API (generated at build by doxygen + doxybook2, not stored in git)
├── group__TPM2__Proprietary.md .. native TPM 2.0 API
├── group__wolfTPM2__Wrappers.md . wolfTPM2 wrapper API
├── tpm2_8h.md ................... tpm2.h
├── tpm2__wrap_8h.md ............. tpm2_wrap.h
└── tpm__io_8h.md ............... tpm_io.h

Legacy (kept as redirect stubs to the website manual, not nav pages)
└── FWTPM.md, SWTPM.md, DEVTPM.md, WindowTBS.md

• merge documenation pr
• update jenkins to have the below in setup_docs()

# wolfTPM's build wipes html/ on each make; build both targets in one pass
echo "Building docs: wolfTPM..."
( cd wolfTPM && make )

This needs merged first then we can merge wolfSSL/documentation#285

[Copilot]

🟡 Changes recommended

The manual reverses security-sensitive session attributes, contains an unsafe fwTPM initialization example, and omits English HTML from the CI artifact.

5 open findings

• Artifact omits the English HTML build · New
• TPM session encryption attributes are reversed · New
• Initialize context and HALs in the required order · New
• TPMセッション暗号化属性が逆に設定されている · New
• コンテキストとHALを正しい順序で初期化する · New

What changed in this PR

Moves the bilingual wolfTPM manual into the repository and adds tooling to generate website, PDF, and Doxygen API documentation.

Changes:

• Adds English and Japanese manuals covering APIs, integrations, fwTPM, PQC, and SPDM.
• Adds MkDocs/Doxygen build tooling and documentation container.
• Adds CI workflows for validation, artifact generation, and image publishing.

File	Description
tools/​docs-manual/​Makefile	Builds HTML, PDF, and API pages.
tools/​docs-manual/​doxybook.cfg	Configures API Markdown generation.
tools/​docs-manual/​documentation-rev	Pins shared documentation tooling.
tools/​docs_manual.py	Stages and builds both languages.
tools/​check-docs-no-internal-links.sh	Detects internal path leakage.
mkdocs.yml	Defines English site navigation.
mkdocs-ja.yml	Defines Japanese site navigation.
docs/​WindowTBS.md	Redirects legacy Windows documentation.
docs/​tpm2-overview.md	Documents TPM concepts and devices.
docs/​tls-and-certificates.md	Documents TLS and certificate examples.
docs/​testing.md	Documents local tests and CI.
docs/​SWTPM.md	Redirects legacy simulator documentation.
docs/​stm32cube.md	Documents STM32Cube integration.
docs/​sbom-and-compliance.md	Documents SBOM generation.
docs/​project-structure.md	Describes repository structure.
docs/​management-and-gpio.md	Documents management and GPIO tools.
docs/​key-management.md	Documents key-management examples.
docs/​ja/​tpm2-overview.md	Adds Japanese TPM overview.
docs/​ja/​testing.md	Adds Japanese testing guide.
docs/​ja/​stm32cube.md	Adds Japanese STM32Cube guide.
docs/​ja/​sbom-and-compliance.md	Adds Japanese SBOM guide.
docs/​ja/​project-structure.md	Adds Japanese project structure.
docs/​ja/​management-and-gpio.md	Adds Japanese management guide.
docs/​ja/​key-management.md	Adds Japanese key guide.
docs/​ja/​index.md	Adds Japanese manual landing page.
docs/​ja/​hal-io-callback.md	Adds Japanese HAL guide.
docs/​ja/​getting-started.md	Adds Japanese quickstart.
docs/​ja/​fwtpm/​spdm.md	Adds Japanese fwTPM SPDM guide.
docs/​ja/​fwtpm/​post-quantum.md	Adds Japanese fwTPM PQC guide.
docs/​ja/​examples-overview.md	Adds Japanese examples guide.
docs/​ja/​cited-sources.md	Adds Japanese references.
docs/​ja/​benchmarks.md	Adds Japanese benchmarks.
docs/​ja/​api-reference.md	Adds Japanese API overview.
docs/​index.md	Adds English manual landing page.
docs/​hal-io-callback.md	Documents HAL callbacks.
docs/​getting-started.md	Adds build and first-run guide.
docs/​fwtpm/​spdm.md	Documents fwTPM SPDM support.
docs/​fwtpm/​post-quantum.md	Documents fwTPM PQC support.
docs/​fwtpm/​hal-and-porting.md	Documents fwTPM porting.
docs/​examples-overview.md	Summarizes example applications.
docs/​DEVTPM.md	Redirects legacy Linux documentation.
docs/​dev/​docs-build.md	Documents manual maintenance.
docs/​csharp-wrapper.md	Documents the C# wrapper.
docs/​cited-sources.md	Lists manual references.
docs/​benchmarks.md	Documents benchmark results.
docs/​assets/​table-code.css	Styles code inside tables.
docs/​assets/​skin.css	Adds manual site styling.
docs/​api-reference.md	Introduces generated API pages.
docker/​docs/​requirements.txt	Pins MkDocs.
docker/​docs/​Dockerfile	Builds the documentation image.
.gitignore	Tracks the documentation Makefile.
.github/​workflows/​publish-docs-image.yml	Publishes the builder image.
.github/​workflows/​docs-site.yml	Builds and uploads manual outputs.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[yosuke-wolfssl]

Thanks for pulling the manual in-tree. The nav parity between mkdocs.yml and mkdocs-ja.yml, the link checker and the docs-site workflow setup all look good. Requesting changes because several commands and defaults a first-time reader runs don't match configure.ac. The tooling also has one build-order bug.

Inline comments cover the ones a reader hits first. A few themes:

• swTPM default. On any non-Windows x86_64/aarch64 host, including macOS, configure.ac:253-289 turns --enable-swtpm (and --enable-fwtpm) on unless a hardware flag is given. Several pages describe builds as if it were off: the fwTPM TIS build, the "plain build autodetects" claim, and pinning SPI with --enable-spi. build-options.md:84-96 gets this right, so the other pages should follow it.
• PQC. The wolfSSL floor is post-v5.9.1 (wc_MlDsaKey_Init), not 5.8.0. And --enable-pqc is not an alias of --enable-v185.
• Tooling. make all runs pdf-prep before html-prep, and pdf-prep rewrites api/md in place. The HTML API pages then get PDF-style anchors, which accounts for the ~80 anchor warnings in the CI log.

Two things can't be inline comments because the PR doesn't touch those files:

• Dead links to the stub pages and deleted README sections:
  • src/fwtpm/README.md:16,163
  • examples/pqc/README.md:10,80,161
  • docs/README.md:52,94 (the Doxygen main page)
  • wolftpm/tpm2_wrap.h:3890,3913, which render into the API pages
  • wolftpm/fwtpm/fwtpm.h:231
  • wrapper/CSharp/README.md:29
• Website links: a minor note, since I expect you already have this in hand. The manual URLs in README.md and the four stubs will resolve once wolfSSL/documentation#285 is merged and the site is published, so landing the two together would keep them working.

I'll send you the rest separately as a list so this review stays readable. It covers lower-severity EN accuracy items, tooling nits, and the Japanese translation (glossary, headings, and links the JA pages dropped). Most EN fixes also need the same change in docs/ja/.

stale