Skip to content

Commit 523b6c6

Browse files
romandarianaromandariana
committed
Add GitHub Pages documentation
Add docs folder with all needed source files for GitHub Pages documentation. Add .github/workflows/gh-pages.yml and .github/workflows/pr-closed.yml to setup the GitHub Pages deployment workflow. Move the complete documentation from README.md to GitHub Pages. Now README.md contains a succinct introduction and references the comprehensive documentation. Signed-off-by: Alisa-Dariana Roman <[email protected]>
1 parent d2829b5 commit 523b6c6

24 files changed

+2465
-870
lines changed

‎.github/workflows/gh-pages.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
on:
2+
push:
3+
branches:
4+
- main
5+
- dev
6+
- dev/*
7+
pull_request:
8+
9+
jobs:
10+
build-doc:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: actions/setup-python@v5
16+
with:
17+
python-version: "3.x"
18+
19+
- name: Install pip packages
20+
working-directory: docs
21+
run: |
22+
pip install pip --upgrade
23+
pip install -r requirements.txt
24+
25+
- name: Build doc
26+
working-directory: docs
27+
run: |
28+
make html SPHINXOPTS='-W --keep-going'
29+
30+
- name: Store the generated doc
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: html
34+
path: docs/_build/html
35+
36+
deploy-gh-pages:
37+
runs-on: ubuntu-latest
38+
needs: build-doc
39+
permissions:
40+
contents: write
41+
if: ${{ github.ref == 'refs/heads/main' || github.event_name == 'pull_request' }}
42+
43+
steps:
44+
- uses: analogdevicesinc/doctools/gh-pages-deploy@action
45+
with:
46+
name: html

‎.github/workflows/pr-closed.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
on:
2+
pull_request:
3+
types: [closed]
4+
5+
jobs:
6+
clean-gh-pages:
7+
runs-on: ubuntu-latest
8+
permissions:
9+
contents: write
10+
11+
steps:
12+
- uses: analogdevicesinc/doctools/gh-pages-rm-path@action
13+
with:
14+
path: pull/${{ github.event.number }}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,5 @@ kuiper-volume/*
22
.pc
33
*-pc
44
apt-cacher-ng/
5+
6+
docs/_build/

‎README.md‎

Lines changed: 32 additions & 870 deletions
Large diffs are not rendered by default.

‎docs/Makefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
SHELL = /bin/bash
2+
SPHINXOPTS ?=
3+
SPHINXBUILD ?= sphinx-build
4+
SOURCEDIR = .
5+
BUILDDIR = _build
6+
7+
help:
8+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
9+
10+
.PHONY: help Makefile
11+
12+
%: Makefile
13+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/build-flow.rst‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
.. _build-flow:
2+
3+
Build Flow
4+
==========
5+
6+
The Kuiper build process uses Docker to create a controlled environment for
7+
building Debian-based images for Analog Devices products. The build follows
8+
these high-level steps:
9+
10+
1. ``build-docker.sh`` creates a Docker container with all necessary build
11+
dependencies
12+
2. Inside the container, ``kuiper-stages.sh`` orchestrates a series of build
13+
stages
14+
3. Each stage performs specific tasks like system configuration, tool
15+
installation, and boot setup
16+
4. The final image is exported as a zip file to the ``kuiper-volume``
17+
directory on your host machine
18+
19+
This approach ensures consistent builds across different host systems while
20+
allowing full customization through the ``config`` file.
21+
22+
The ``config`` file is first read by ``build-docker.sh`` on the host system
23+
to set up environment variables and Docker options. It is then copied into
24+
the container where ``kuiper-stages.sh`` reads it again to determine which
25+
stages to execute and how to configure them.
26+
27+
.. svg:: sources/build_flow.svg
28+
:align: center
29+
30+
----
31+
32+
Docker Build Environment
33+
------------------------
34+
35+
Docker is used to perform the build inside a container, which partially
36+
isolates the build from the host system. This allows the script to work on
37+
non-Debian based systems (e.g., Fedora Linux). The isolation is not total
38+
due to the need to use some kernel-level services for ARM emulation (binfmt)
39+
and loop devices (losetup).
40+
41+
The ``build-docker.sh`` script handles:
42+
43+
- Checking prerequisites and permissions
44+
- Building a Docker image with all necessary dependencies
45+
- Running a Docker container with appropriate options
46+
- Mounting volumes to share data between the host and container
47+
- Setting environment variables based on the ``config`` file
48+
- Starting the internal build process by calling ``kuiper-stages.sh``
49+
- Cleaning up the container after completion (if ``PRESERVE_CONTAINER=n``)
50+
51+
Running the Build
52+
~~~~~~~~~~~~~~~~~
53+
54+
To build:
55+
56+
.. code-block:: bash
57+
58+
sudo ./build-docker.sh
59+
60+
Your Kuiper image will be in the ``kuiper-volume/`` folder inside the cloned
61+
repository on your machine as a zip file named
62+
``image_YYYY-MM-DD-ADI-Kuiper-Linux-[arch].zip``. After successful build,
63+
the Docker image and the build container are removed if
64+
``PRESERVE_CONTAINER=n``.
65+
66+
If needed, you can remove the build container with:
67+
68+
.. code-block:: bash
69+
70+
docker rm -v debian_<DEBIAN_VERSION>_rootfs_container
71+
72+
If you choose to preserve the Docker container, you can access the Kuiper
73+
root filesystem by copying it from the container to your machine with this
74+
command:
75+
76+
.. code-block:: bash
77+
78+
CONTAINER_ID=$(docker inspect --format="{{.Id}}" debian_<DEBIAN_VERSION>_rootfs_container)
79+
sudo docker cp $CONTAINER_ID:<TARGET_ARCHITECTURE>_rootfs .
80+
81+
You need to replace ``<DEBIAN_VERSION>`` and ``<TARGET_ARCHITECTURE>`` with
82+
the ones in the configuration file.
83+
84+
Example:
85+
86+
.. code-block:: bash
87+
88+
CONTAINER_ID=$(docker inspect --format="{{.Id}}" debian_bookworm_rootfs_container)
89+
sudo docker cp $CONTAINER_ID:armhf_rootfs .
90+
91+
Docker Container Configuration
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
When the Docker container is run, various required command line arguments
95+
are provided:
96+
97+
- ``-t``: Allocates a pseudo-TTY allowing interaction with container's shell
98+
- ``--privileged``: Provides elevated privileges required by the chroot
99+
command
100+
- ``-v /dev:/dev``: Mounts the host system's device directory
101+
- ``-v /lib/modules:/lib/modules``: Mounts kernel modules from the host
102+
- ``-v ./kuiper-volume:/kuiper-volume``: Creates a shared volume for the
103+
output
104+
- ``-e "DEBIAN_VERSION={value}"``: Sets environment variables from the config
105+
file
106+
107+
The ``--name`` and ``--privileged`` options are already set by the script and
108+
should not be redefined.
109+
110+
----
111+
112+
Stage-Based Build Process
113+
-------------------------
114+
115+
Inside the Docker container, ``kuiper-stages.sh`` orchestrates the entire
116+
build process. This script reads the ``config`` file, sets up environment
117+
variables, and executes a series of stages in a specific order.
118+
119+
How Stages Are Processed
120+
~~~~~~~~~~~~~~~~~~~~~~~~
121+
122+
The build process follows these steps inside the Docker container:
123+
124+
1. ``kuiper-stages.sh`` loops through the ``stages`` directory in
125+
alphanumeric order
126+
2. Within each stage, it processes subdirectories in alphanumeric order
127+
3. For each subdirectory, it runs the following files if they exist:
128+
129+
- ``run.sh`` - A shell script executed in the Docker container's context
130+
- ``run-chroot.sh`` - A shell script executed within the Kuiper image
131+
using chroot
132+
- Package installation files:
133+
134+
- ``packages-[*]`` - Lists packages to install with
135+
``--no-install-recommends``
136+
- ``packages-[*]-with-recommends`` - Lists packages to install with
137+
their recommended dependencies
138+
139+
The package installation files (``packages-[*]``) are processed if the
140+
corresponding configuration option is enabled. For example,
141+
``packages-desktop`` is only processed if ``CONFIG_DESKTOP=y`` in the config
142+
file.
143+
144+
Key Stages Overview
145+
~~~~~~~~~~~~~~~~~~~
146+
147+
The build process is divided into several stages for logical clarity and
148+
modularity:
149+
150+
- **01.bootstrap** - Creates a usable filesystem using ``debootstrap``
151+
- **02.set-locale-and-timezone** - Configures system locale and timezone
152+
settings
153+
- **03.system-tweaks** - Sets up users, passwords, and system configuration
154+
- **04.configure-desktop-env** - Installs and configures desktop environment
155+
(if enabled)
156+
- **05.adi-tools** - Installs Analog Devices libraries and tools (based on
157+
config)
158+
- **06.boot-partition** - Adds boot files for different platforms
159+
- **07.extra-tweaks** - Applies custom scripts and additional configurations
160+
- **08.export-stage** - Creates and exports the final image
161+
162+
Each stage contains multiple substages that handle specific aspects of the
163+
build process. The stages are designed to be modular, allowing for easy
164+
customization and extension.
165+
166+
For a more detailed description of each stage and its purpose, see the
167+
:doc:`Stage Reference <stage-reference>` section.
168+
169+
Stage Execution Logic
170+
~~~~~~~~~~~~~~~~~~~~~
171+
172+
The ``kuiper-stages.sh`` script contains a helper function called
173+
``install_packages`` that handles package installation for each stage. This
174+
function:
175+
176+
1. Checks if package files exist for the current stage
177+
2. Verifies if the corresponding configuration option is enabled
178+
3. Installs the packages using the appropriate apt-get command
179+
180+
The script then executes each stage's ``run.sh`` script, which may perform
181+
additional configuration steps, compile software from source, or prepare
182+
files for the final image.
183+
184+
This modular approach allows users to easily customize the build process by
185+
modifying existing stages or adding new ones.

‎docs/conf.py‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# -- Import setup -------------------------------------------------------------
2+
3+
from os import path
4+
import os
5+
6+
# -- Project information ------------------------------------------------------
7+
8+
repository = 'adi-kuiper-gen'
9+
project = 'Kuiper'
10+
copyright = '2025, Analog Devices, Inc.'
11+
author = 'Analog Devices, Inc.'
12+
13+
# Version from environment variable or fallback
14+
version = os.environ.get('ADOC_DOC_VERSION', 'latest')
15+
16+
# -- General configuration ----------------------------------------------------
17+
18+
extensions = [
19+
'sphinx.ext.todo',
20+
'adi_doctools',
21+
]
22+
23+
needs_extensions = {
24+
'adi_doctools': '0.3.47'
25+
}
26+
27+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
28+
source_suffix = '.rst'
29+
30+
# -- Numbered references configuration ----------------------------------------
31+
32+
numfig = True
33+
numfig_format = {
34+
'figure': 'Figure %s',
35+
'table': 'Table %s',
36+
'code-block': 'Listing %s',
37+
'section': 'Section %s'
38+
}
39+
40+
# -- External docs configuration ----------------------------------------------
41+
42+
interref_repos = []
43+
44+
# -- Custom extensions configuration ------------------------------------------
45+
46+
hide_collapsible_content = True
47+
validate_links = False
48+
49+
# -- todo configuration -------------------------------------------------------
50+
51+
todo_include_todos = True
52+
todo_emit_warnings = True
53+
54+
# -- Options for HTML output --------------------------------------------------
55+
56+
html_theme = 'cosmic'
57+
html_static_path = ['sources']
58+
html_favicon = path.join("sources", "icon.png")
59+
60+
html_theme_options = {
61+
"light_logo": "logo_light.png",
62+
"dark_logo": "logo_dark.png",
63+
}

0 commit comments

Comments
 (0)