Documentation Workflow

This project uses mdBook to generate documentation, with GitHub Actions for automated builds and GitHub Pages for hosting.

Repository Layout

Documentation source files live alongside the Yocto BSP layer content:

meta-tegra/
├── book.toml                      # mdBook configuration
├── docs/                          # Documentation source (markdown)
│   ├── SUMMARY.md                 # Table of contents for mdBook
│   ├── README.md                  # Introduction / landing page
│   ├── *.md                       # Documentation pages
│   └── mdbook/                    # Custom mdBook assets
│       ├── css/custom.css         # Version dropdown styling
│       └── js/version-dropdown.js # Version switching logic
└── .github/workflows/
    └── mdbook-versioned.yml       # CI/CD workflow

The book.toml in the repository root configures mdBook. The src setting points to the docs/ directory, and custom CSS and JavaScript are loaded for the version dropdown:

[book]
title = "OE4T Meta Tegra"
authors = ["Matt Madison", "Dan Walkes"]
language = "en"
src = "docs"

[output.html]
additional-css = ["docs/mdbook/css/custom.css"]
additional-js = ["docs/mdbook/js/version-dropdown.js"]

Multi-Version Support

Each tracked branch gets its own independent copy of the documentation on GitHub Pages. The list of published versions is controlled by a versions.json file in the GitHub Pages content repository (OE4T/oe4t.github.io).

Adding Pages

All documentation pages are Markdown files in the docs/ directory. To add a new page:

1. Create a new .md file in docs/.
2. Add an entry for it in docs/SUMMARY.md. The SUMMARY file defines the table of contents and sidebar navigation. Pages not listed in SUMMARY.md will not appear in the built documentation.

Page Editing Tips

• Please ensure any embedded links to other documentation files are done with relative paths. For example, use [Link to another page in docs](OtherPageName.md) instead of [Link to another page in docs](https://github.com/OE4T/meta-tegra/blob/master/docs/OtherPageName.md)
• You can use the trick at this stackoverflow post to add images to your markdown file without the need to check images into the repo.

Preview Locally

To preview the documentation locally with markdown, install mdBook and run:

mdbook serve

This starts a local web server with live reloading as you edit files.

Build and Deploy

The GitHub Actions workflow (.github/workflows/mdbook-versioned.yml) triggers on pushes to tracked branches:

1. Build — runs mdbook build inside a peaceiris/mdbook container, producing output in a per-branch directory.
2. Deploy — pushes the built HTML to a subdirectory in the main branch of the external GitHub Pages content repository (OE4T/oe4t.github.io) using peaceiris/actions-gh-pages.

Each branch deploys to its own directory, resulting in a structure like this in OE4T/oe4t.github.io:

<repo-root>/
├── index.html          # redirects to ./master/
├── versions.json       # lists available versions for the dropdown
├── master/             # docs built from the master branch
└── scarthgap/          # docs built from the scarthgap branch

The workflow can also be triggered manually via workflow_dispatch from the GitHub Actions UI.

Deployment credentials

The deploy step requires an SSH deploy key stored as a repository secret:

• OE4T_GITHUB_DEPLOY_KEY

If the secret is missing (common in forks), the workflow will emit a warning: “The repository secret must contain the OE4T_GITHUB_DEPLOY_KEY to run this step.” Then it will skip the deploy step without failing the workflow.

Version Dropdown

A custom JavaScript file (docs/mdbook/js/version-dropdown.js) adds a version selector dropdown to the mdBook navigation bar. It fetches versions.json from the site root to populate the list, and when a different version is selected it navigates to the same page path under the new version’s directory.

The versions.json file is maintained manually in the GitHub Pages content repository (OE4T/oe4t.github.io, main branch) (not auto-generated), giving explicit control over which versions appear in the dropdown.

Adding a New Version

To add documentation for a new branch (e.g., kirkstone):

1. Add the branch name to the on.push.branches list in .github/workflows/mdbook-versioned.yml.
2. Push content to that branch. The workflow will automatically build and deploy to a new directory in OE4T/oe4t.github.io.
3. Update versions.json in OE4T/oe4t.github.io (on the main branch) to include the new entry so it appears in the version dropdown.