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.

Listing 4 .gitlab-ci.yml#
 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