Building the Documentation#
We chose Sphinx as our tool for documenting BeagleBoard.org projects due to its popular use in Linux and Zephyr, two open source projects we respect a lot. This page is intended to document specific aspects of the process of turning the Docs Git Repo into the Docs Page. This should help newcomers figure it out and those of us working on it a lot to simply remember what we did.
Invoking Sphinx#
We rely primarily on invoking Sphinx from the OpenBeagle CI.
1image: beagle/sphinx-build-env:latest
2
3variables:
4 GIT_SUBMODULE_STRATEGY: recursive
5
6cache:
7 key: sphinx-build-env-docs-003
8 paths:
9 - .venv
10 - .cache
11
12build:
13 stage: build
14 tags:
15 - docker-amd64
16 parallel:
17 matrix:
18 - TARGET: [html, pdf]
19 artifacts:
20 paths:
21 - public/$TARGET
22 before_script:
23 - source ./venv-build-env.sh
24 script:
25 - ./gitlab-build.sh $TARGET
26
27pages:
28 stage: deploy
29 dependencies:
30 - "build: [html]"
31 - "build: [pdf]"
32 tags:
33 - docker-amd64
34 script:
35 - ./gitlab-build.sh publish
36 artifacts:
37 paths:
38 - public
39 except:
40 - tags
41
42docs:
43 stage: deploy
44 dependencies:
45 - "build: [html]"
46 - "build: [pdf]"
47 tags:
48 - docker-amd64
49 script:
50 - ./gitlab-build.sh publish
51 artifacts:
52 paths:
53 - public
54 only:
55 - tags
56 except:
57 - branches
Building your fork with GitHub Actions#
A mirror of the repository on GitHub builds the same way. Enable Actions and set Pages to build from GitHub Actions in your fork, then every push builds the HTML and the PDFs and publishes them together, with each PDF sitting next to the HTML so the Download PDF button on a board page finds it.
The site addresses itself to your fork, so username.github.io/docs.beagleboard.io
serves your build and its links stay inside it. Only the upstream repository publishes to
docs.beagleboard.org, which happens when a tag is pushed.
1name: "Sphinx: Render docs"
2
3on:
4 push:
5 branches: ["*"]
6 tags: ["*"]
7
8jobs:
9 build:
10 runs-on: ubuntu-latest
11
12 container:
13 image: beagle/sphinx-build-env:latest
14
15 defaults:
16 run:
17 shell: bash
18
19 strategy:
20 # An HTML failure should not cancel a PDF build that is hours in
21 fail-fast: false
22 matrix:
23 target: [html, pdf]
24
25 steps:
26 - name: Checkout repository with submodules
27 uses: actions/checkout@v4
28 with:
29 submodules: recursive
30
31 - name: Build docs (${{ matrix.target }})
32 run: |
33 source ./venv-build-env.sh
34 ./github-build.sh ${{ matrix.target }}
35
36 - name: Upload ${{ matrix.target }} artifacts
37 uses: actions/upload-artifact@v4
38 with:
39 name: docs-${{ matrix.target }}
40 path: public/${{ matrix.target }}
41
42 publish:
43 needs: build
44 runs-on: ubuntu-latest
45 if: github.ref_type == 'branch'
46
47 permissions:
48 pages: write
49 id-token: write
50
51 environment:
52 name: github-pages
53 url: ${{ steps.deployment.outputs.page_url }}
54
55 steps:
56 - name: Checkout repository
57 uses: actions/checkout@v4
58
59 - name: Download HTML docs
60 uses: actions/download-artifact@v4
61 with:
62 name: docs-html
63 path: public/html
64
65 - name: Download PDF docs
66 uses: actions/download-artifact@v4
67 with:
68 name: docs-pdf
69 path: public/pdf
70
71 # Puts the PDFs next to the HTML, where the Download PDF button points
72 - name: Combine artifacts
73 run: ./github-build.sh publish
74
75 - name: List published files
76 run: ls -lR public
77
78 - name: Upload to Pages artifact
79 uses: actions/upload-pages-artifact@v3
80 with:
81 path: public
82
83 - name: Deploy to GitHub Pages
84 id: deployment
85 uses: actions/deploy-pages@v4