Installation¶

The action needs no installation: a workflow of your model’s repository uses it, and GitHub fetches it. This page publishes the NED reference of a model; A Sphinx Site adds your own pages.

The workflow¶

.github/workflows/docs.yml in your model repository:

name: Documentation

on:
  push:
    branches: [master]
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
      - uses: omnetpp/doc-builder@v1

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

The deployment is a second job, because it needs permissions that the build does not.

Enabling GitHub Pages¶

Once, in the settings of the repository: Settings → Pages → Build and deployment → Source: GitHub Actions. The next run of the workflow publishes the site, at https://<owner>.github.io/<repository>/.

What it publishes¶

The NED reference of the project, in the repository root, in the look of the NED documentation of the Eclipse-based IDE (ned-format: html-material; html-readthedocs and html are the other choices). The NED folders of the project are taken from its .nedfolders file, like in the IDE.

Add doxygen: true to also publish the C++ API, under api/. The NED types’ pages then link to their C++ classes (“C++ definition”):

- uses: omnetpp/doc-builder@v1
  with:
    doxygen: true

The workflow of this site¶

This site is deployed by the workflow below, from the site/ directory of the doc-builder repository. It builds the site three times: the site itself, with the C++ API and a PDF, and two variants of it into subdirectories, so it uploads the Pages artifact itself.

# Builds the website of this repository (site/) with the action, the way a model project uses it, and deploys
# it to GitHub Pages. Two variants of the site, in variants/, show what settings that apply to the whole site
# change. The site documents the released action, so it is built on pushes to the release branch.
name: Pages

on:
  push:
    branches: [v1]
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7

      - uses: omnetpp/doc-builder@v1
        with:
          project-dir: site
          title: Sample Model
          sphinx-source: site/doc
          doxygen: true
          pdf: true
          fail-on-warnings: true
          upload-pages-artifact: false

      # The tabs open no menus
      - uses: omnetpp/doc-builder@v1
        with:
          project-dir: site
          title: Sample Model
          sphinx-source: site/doc
          doxygen: true
          sphinx-args: -t variant -D omnetpp_nav_menus=0
          fail-on-warnings: true
          output-dir: _site/variants/no-menus
          upload-pages-artifact: false

      # The NED reference alone, without a Sphinx project: what the quick start publishes
      - uses: omnetpp/doc-builder@v1
        with:
          project-dir: site
          title: Sample Model
          doxygen: true
          fail-on-warnings: true
          output-dir: _site/variants/ned-only
          upload-pages-artifact: false

      - uses: actions/upload-pages-artifact@v5
        with:
          path: _site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5