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: registry.git.beagleboard.org/docs/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