diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 7a2cb6b1beed8206f128a47a8d6f1762a0a21458..ef29f39f598f7f8198b0a1f8f2dc411c0bcc8138 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -4,15 +4,35 @@ variables:
GIT_SUBMODULE_STRATEGY: recursive
cache:
- key: bbdocs
+ key: sphinx-build-env-docs-001
paths:
- - public
+ - .venv
+ - .cache
+
+build:
+ stage: build
+ tags:
+ - docker-amd64
+ parallel:
+ matrix:
+ - TARGET: [html, pdf]
+ artifacts:
+ paths:
+ - public/$TARGET
+ before_script:
+ - source ./venv-build-env.sh
+ script:
+ - ./gitlab-build.sh $TARGET
pages:
+ stage: deploy
+ dependencies:
+ - "build: [html]"
+ - "build: [pdf]"
tags:
- - docker-arm64
+ - docker-amd64
script:
- - "./gitlab-build.sh"
+ - ./gitlab-build.sh publish
artifacts:
paths:
- public
@@ -20,10 +40,14 @@ pages:
- tags
docs:
+ stage: deploy
+ dependencies:
+ - "build: [html]"
+ - "build: [pdf]"
tags:
- docs
script:
- - "./gitlab-build.sh"
+ - ./gitlab-build.sh publish
artifacts:
paths:
- public
diff --git a/boards/beagleconnect/freedom/02-quick-start.rst b/boards/beagleconnect/freedom/02-quick-start.rst
index 6fa46260278d6338a3ebc6fb48ff8916153b57b9..886fe178e343922fd1e8b404931173624bd03aff 100644
--- a/boards/beagleconnect/freedom/02-quick-start.rst
+++ b/boards/beagleconnect/freedom/02-quick-start.rst
@@ -15,25 +15,10 @@ What's included in the box?
Image with what's inside the box and a better description.
-.. only:: latex
-
- .. image:: https://img.youtube.com/vi/bJYZ6PTiV9g/maxresdefault.jpg
- :alt: BeagleConnect unboxing YouTube video
- :width: 1280
- :target: https://www.youtube.com/watch?v=bJYZ6PTiV9g
-
-.. only:: html
-
- .. raw:: html
-
- <iframe style="display: block; margin: auto;" width="1280" height="720" style="align:center"
- src="https://www.youtube.com/embed/bJYZ6PTiV9g"
- title="YouTube video player"
- frameborder="0"
- allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
- allowfullscreen>
- </iframe>
-
+.. youtube:: bJYZ6PTiV9g
+ :align: center
+ :width: 1280
+ :height: 720
Attaching antenna
******************
diff --git a/boards/beagleplay/02-quick-start.rst b/boards/beagleplay/02-quick-start.rst
index f8af1f75ce494f028627cee84cbce0b2ee39e56a..57b909bfc4606f67712a8aa7ede93d014014eeeb 100644
--- a/boards/beagleplay/02-quick-start.rst
+++ b/boards/beagleplay/02-quick-start.rst
@@ -24,24 +24,12 @@ Attaching antennas
You can watch this video to see how to attach the attennas.
-.. only:: latex
-
- .. image:: images/attach-antennas.*
- :alt: YouTube video of BeaglePlay antenna connection
- :width: 1280
- :target: https://youtu.be/8zeIVd-JRc0
-
-.. only:: html
+.. admonition:: YouTube video of BeaglePlay antenna connection
- .. raw:: html
-
- <iframe style="display: block; margin: auto;" width="920" height="520" style="align:center"
- src="https://www.youtube.com/embed/8zeIVd-JRc0"
- title="YouTube video player"
- frameborder="0"
- allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
- allowfullscreen>
- </iframe>
+ .. youtube:: 8zeIVd-JRc0
+ :width: 1280
+ :height: 720
+ :align: center
Tethering to PC
****************
@@ -57,7 +45,7 @@ Tethering to PC
For tethering to your PC you'll need a USB-C data cable.
-.. figure:: images/tethered-connection.jpg
+.. figure:: images/tethered-connection.*
:width: 1400
:align: center
:alt: Tethering BeaglePlay to PC
@@ -76,7 +64,7 @@ to browse documents and start programming your BeaglePlay!
not having a public URL for your board. If you have any questions about this, please as on
https://forum.beagleboard.org/tag/play.
-.. figure:: images/vscode.png
+.. figure:: images/vscode.*
:width: 1400
:align: center
:alt: BeaglePlay VSCode IDE (192.168.7.2:3000)
diff --git a/boards/beagleplay/03-design.rst b/boards/beagleplay/03-design.rst
index 75bf2404e8cb35983132a63f5b5a1bc6b221b89e..86b84b9198be2872daf81bb95d3e4dd2a47e314e 100644
--- a/boards/beagleplay/03-design.rst
+++ b/boards/beagleplay/03-design.rst
@@ -501,14 +501,14 @@ Dimensions & Weight
| Weight | 55.3g |
+--------------------+----------------------------------------------------+
-.. figure:: images/dimensions.png
+.. figure:: images/dimensions.*
:width: 700
:align: center
:alt: BeaglePlay board dimensions
BeaglePlay board dimensions
-.. figure:: images/side-dimensions.png
+.. figure:: images/side-dimensions.*
:width: 700
:align: center
:alt: BeaglePlay board side dimensions
diff --git a/boards/beagleplay/demos-and-tutorials/connect-wifi.rst b/boards/beagleplay/demos-and-tutorials/connect-wifi.rst
index f4e13356568c388cc1b4e02e408694205023d471..dcc385c82f8a9f88e42813662cd9a6921ab51ef6 100644
--- a/boards/beagleplay/demos-and-tutorials/connect-wifi.rst
+++ b/boards/beagleplay/demos-and-tutorials/connect-wifi.rst
@@ -78,13 +78,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
You can start ``wpa_gui`` either from ``Applications > Internet > wpa_gui`` or double click on the ``wpa_gui`` desktop application shortcut.
- .. figure:: ../images/wpa_gui_step1a.png
+ .. figure:: ../images/wpa_gui_step1a.*
:align: center
:alt: Starting wpa_gui from Applications > Internet > wpa_gui
Starting wpa_gui from Applications > Internet > wpa_gui
- .. figure:: ../images/wpa_gui_step1b.png
+ .. figure:: ../images/wpa_gui_step1b.*
:align: center
:alt: Starting wpa_gui from Desktop application shortcut
@@ -102,7 +102,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
- Click on ``Scan`` to scan nearby WiFi access points.
4. ``Manage Network`` tab shows you all the saved networks and options to manage those.
- .. figure:: ../images/wpa_gui_step2.png
+ .. figure:: ../images/wpa_gui_step2.*
:align: center
:alt: wpa_gui interface
@@ -113,7 +113,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
To scan the WiFi access points around you, just click on ``Scan`` button availale under
``wpa_gui > Current Status > Scan``.
- .. figure:: ../images/wpa_gui_step3a.png
+ .. figure:: ../images/wpa_gui_step3a.*
:align: center
:alt: Scanning WiFi access points
@@ -133,7 +133,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
SSIDs and BSSIDs are not fully visible in screenshot below
but you can change the column length to see the WiFi names better.
- .. figure:: ../images/wpa_gui_step3b.png
+ .. figure:: ../images/wpa_gui_step3b.*
:align: center
:alt: Selecting WiFi access point
@@ -204,13 +204,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
Open up a terminal window either from ``Applications > Terminal Emulator`` Or from Task Manager.
- .. figure:: ../images/wpa_cli_step1a.jpg
+ .. figure:: ../images/wpa_cli_step1a.*
:align: center
:alt: Open terminal from Applications > Terminal Emulator
Open terminal from Applications > Terminal Emulator
- .. figure:: ../images/wpa_cli_step1b.jpg
+ .. figure:: ../images/wpa_cli_step1b.*
:align: center
:alt: Open terminal from Task Manager
@@ -222,7 +222,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
1. Execute ``sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf``,
which will open up ``wpa_supplicant-wlan0.conf`` inside ``nano`` (terminal based) text editor.
- 1. Edit ``wpa_supplicant-wlan0.conf`` to add SSID (WiFi name) & PSK (WiFi password) of your WiFi access point.
+ 2. Edit ``wpa_supplicant-wlan0.conf`` to add SSID (WiFi name) & PSK (WiFi password) of your WiFi access point.
.. code-block::
@@ -236,19 +236,19 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
1. Now save the details using ``ctrl + O`` then enter.
2. To exit out of the ``nano`` text editor use ``ctrl + X``.
- .. figure:: ../images/wpa_cli_step2a.jpg
+ .. figure:: ../images/wpa_cli_step2a.*
:align: center
:alt: Run: $ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
Run: $ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
- .. figure:: ../images/wpa_cli_step2b.jpg
+ .. figure:: ../images/wpa_cli_step2b.*
:align: center
:alt: Add SSID and PSK
Add SSID and PSK
- .. figure:: ../images/wpa_cli_step2c.jpg
+ .. figure:: ../images/wpa_cli_step2c.*
:align: center
:alt: Save credentials and Exit
@@ -281,13 +281,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
rtt min/avg/max/mdev = 5.281/6.445/9.043/1.274 ms
- .. figure:: ../images/wpa_cli_step3a.jpg
+ .. figure:: ../images/wpa_cli_step3a.*
:align: center
:alt: Connect to WiFi by running $ sudo wpa_cli -i wlan0 reconfigure
Connect to WiFi by running $ sudo wpa_cli -i wlan0 reconfigure
- .. figure:: ../images/wpa_cli_step3b.jpg
+ .. figure:: ../images/wpa_cli_step3b.*
:align: center
:alt: To check connection try running $ ping 8.8.8.8
diff --git a/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.jpg b/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.jpg
deleted file mode 100644
index 3010bdd35d2d2d2f657ba5389ab340b33b8ac66f..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.jpg and /dev/null differ
diff --git a/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.webp b/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.webp
new file mode 100644
index 0000000000000000000000000000000000000000..efdbb2f19015a1133831993b86725a1921e5a2d5
Binary files /dev/null and b/boards/beagleplay/demos-and-tutorials/images/serial-debug-connection.webp differ
diff --git a/boards/beagleplay/demos-and-tutorials/understanding-boot.rst b/boards/beagleplay/demos-and-tutorials/understanding-boot.rst
index 04dc6520eb7005ef8a33777d8e32a73d0651bc4b..e7381f86a6df90060eb83b2dcd7c1a7df7cdf050 100644
--- a/boards/beagleplay/demos-and-tutorials/understanding-boot.rst
+++ b/boards/beagleplay/demos-and-tutorials/understanding-boot.rst
@@ -8,17 +8,14 @@ the system is using :ref:`play-distro-boot`. It is simplest because it is very g
not at all specific to BeaglePlay or AM62, and was included in the earliest BeagleBoard.org Debian
images shipping pre-installed in the on-board flash.
-Over time, BeaglePlay images will include `SystemReady
-support <https://www.arm.com/architecture/system-architectures/systemready-certification-program>`_ to
-provide for the most generic boot support allowing execution of
-
.. _play-distro-boot:
Distro Boot
***********
For some background on distro boot, see `the u-boot documentation on
-distro boot <https://docs.u-boot.org/en/latest/develop/distro.html>`_.
+distro boot <https://docs.u-boot.org/en/latest/develop/distro.html>`_. There is
+also `BeaglePlay specific u-boot documentation <https://docs.u-boot.org/en/latest/board/ti/am62x_beagleplay.html>`_.
In :ref:`play-typical-extlinux-conf`, you can see line 1 provides a label
and subsequent indented lines provide parameters for that boot option.
@@ -76,33 +73,58 @@ The FAT32 partition in this setup is often referred to as the boot file system.
/dev/mmcblk0p2 264192 30621695 30357504 14.5G 83 Linux
-To better understand BeaglePlay's U-Boot Distro Boot, let's install the kernel image
-we made in :ref:`play-kernel-development`. To do this, we need to have an uncompressed
-version of the kernel in the FAT32 file system and a ramdisk image we plan to use. The
-ramdisk image is utilized to make sure any kernel modules needed are available and to
-provide a bit of a recovery opportunity in case the root file system is corrupted. You
-can learn more about initrd on `the Debian Initrd Wiki page <https://wiki.debian.org/Initrd>`
-and `the Linux kernel documentation admin guide initrd
-entry <https://docs.kernel.org/admin-guide/initrd.html>`.
+To better understand BeaglePlay's U-Boot Distro Boot, let's install a Linux kernel and
+initramfs from the `Buildroot project <http://buildroot.org/>`_. There is a pre-built image
+release at https://git.beagleboard.org/beagleboard/buildroot/-/releases/2023.11-beagle1.
-In :ref:`play-copy-kernel`, we perform a copy of the kernel that was installed via
-:ref:`play-dpkg-install-kernel` and then reverted with ...
+Currently, the Linux kernel image needs to be uncompressed and stored in the FAT32 file
+system. An initramfs image is a simple way to provide a starting root file system. When
+running Linux, some kind of root file system is required.
-.. todo::
+An initramfs image is utilized on Debian systems to make sure any kernel modules needed are
+available and to provide a bit of a recovery opportunity in case the root file system is
+corrupted. You can learn more about initramfs and initrd on `the Debian Initrd Wiki
+page <https://wiki.debian.org/Initrd>` and `the Linux kernel documentation admin
+guide initrd entry <https://docs.kernel.org/admin-guide/initrd.html>`.
- Put the step into play-kernel-development.rst to revert back to the Beagle kernel.
+In the case of utilizing Buildroot, the
+entire `Linux distribution <https://en.wikipedia.org/wiki/Linux_distribution>`_ is
+incorporated into the initramfs root file system image.
-The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd.img-6.6.0``.
+The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd.img``.
.. _play-copy-kernel:
.. code-block:: shell-session
:caption: Copy kernel to FAT32 filesystem
- debian@BeaglePlay:~$ sudo cp /boot/vmlinuz-6.6.0 /boot/firmware/Image-6.6.gz
- [sudo] password for debian:
- debian@BeaglePlay:~$ sudo gunzip /boot/firmware/Image-6.6.gz
- debian@BeaglePlay:~$ sudo cp /boot/initrd.img-6.6.0 /boot/firmware/
+ debian@BeaglePlay:~$ wget https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/Image
+ --2023-12-19 22:17:54-- https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/Image
+ Resolving git.beagleboard.org (git.beagleboard.org)... 44.226.162.25
+ Connecting to git.beagleboard.org (git.beagleboard.org)|44.226.162.25|:443... connected.
+ HTTP request sent, awaiting response... 200 OK
+ Length: 32172544 (31M) [application/octet-stream]
+ Saving to: ‘Image’
+
+ Image 100%[===================>] 30.68M 1.78MB/s in 18s
+
+ 2023-12-19 22:18:13 (1.74 MB/s) - ‘Image’ saved [32172544/32172544]
+
+ debian@BeaglePlay:~$ sudo cp Image /boot/firmware/Image-buildroot
+ [sudo] password for debian:
+ debian@BeaglePlay:~$ wget https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/rootfs.cpio.gz
+ --2023-12-19 22:16:44-- https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/rootfs.cpio.gz
+ Resolving git.beagleboard.org (git.beagleboard.org)... 44.226.162.25
+ Connecting to git.beagleboard.org (git.beagleboard.org)|44.226.162.25|:443... connected.
+ HTTP request sent, awaiting response... 200 OK
+ Length: 30111086 (29M) [application/octet-stream]
+ Saving to: ‘rootfs.cpio.gz’
+
+ rootfs.cpio.gz 100%[===================>] 28.72M 21.5MB/s in 1.3s
+
+ 2023-12-19 22:16:46 (21.5 MB/s) - ‘rootfs.cpio.gz’ saved [30111086/30111086]
+
+ debian@BeaglePlay:~$ sudo cp rootfs.cpio.gz /boot/firmware/rootfs.cpio.gz-buildroot
.. _play-modified-extlinux-conf:
@@ -111,48 +133,55 @@ The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd
:linenos:
menu title Select image to boot
- timeout 30
- default Linux 6.6
+ timeout 10
+ default Buildroot
- label Linux default
+ label Debian
kernel /Image
append root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait net.ifnames=0 quiet
fdtdir /
#fdtoverlays /overlays/<file>.dtbo
initrd /initrd.img
- label Linux 6.6
- kernel /Image-6.6
- append root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait net.ifnames=0 quiet
+ label Buildroot
+ kernel /Image-buildroot
+ append rootwait net.ifnames=0 quiet
fdtdir /
- initrd /initrd.img-6.6.0
+ initrd /rootfs.cpio.gz-buildroot
.. _play-boot-modified-kernel:
.. code-block:: shell-session
- :caption: Reboot into modified kernel
+ :caption: Reboot into modified kernel and rootfs
debian@BeaglePlay:~$ sudo shutdown -r now
Connection to 192.168.0.117 closed by remote host.
Connection to 192.168.0.117 closed.
- jkridner@slotcar:~$ ssh -Y debian@192.168.0.117
- Debian GNU/Linux 11
-
- BeagleBoard.org Debian Bullseye Xfce Image 2023-05-18
- Support: https://bbb.io/debian
- default username:password is [debian:temppwd]
-
- debian@192.168.0.117's password:
-
- The programs included with the Debian GNU/Linux system are free software;
- the exact distribution terms for each program are described in the
- individual files in /usr/share/doc/\*/copyright.
-
- Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
- permitted by applicable law.
- Last login: Tue Dec 12 15:33:21 2023 from 192.168.0.171
- debian@BeaglePlay:~$ uname -a
- Linux BeaglePlay 6.6.0 #4 SMP Tue Dec 5 13:50:59 UTC 2023 aarch64 GNU/Linux
+ jkridner@slotcar:~$ sudo nmap -n -p 22 192.168.0.0/24
+ Starting Nmap 7.94SVN ( https://nmap.org ) at 2023-12-19 17:32 EST
+ ...
+ PORT STATE SERVICE
+ 22/tcp open ssh
+ MAC Address: 50:3E:AA:AD:78:06 (TP-Link Technologies)
+
+ Nmap scan report for 192.168.0.112
+ Host is up (0.00020s latency).
+ ...
+ jkridner@slotcar:~$ ssh root@192.168.0.112
+ The authenticity of host '192.168.0.112 (192.168.0.112)' can't be established.
+ ED25519 key fingerprint is SHA256:EZdvLkCNMyhy4RhvseUSC5EwaJR5Kgpk8JZG9kF+pmk.
+ This key is not known by any other names.
+ Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
+ Warning: Permanently added '192.168.0.112' (ED25519) to the list of known hosts.
+ root@192.168.0.112's password:
+ # uname -a
+ Linux BeaglePlay 6.6.3 #1 SMP Tue Dec 19 21:32:06 UTC 2023 aarch64 GNU/Linux
+ # cat /etc/os-release
+ NAME=Buildroot
+ VERSION=2023.11-beagle1
+ ID=buildroot
+ VERSION_ID=2023.11
+ PRETTY_NAME="Buildroot 2023.11"
Booting U-Boot
diff --git a/boards/beagleplay/demos-and-tutorials/using-serial-console.rst b/boards/beagleplay/demos-and-tutorials/using-serial-console.rst
index 3900b2525eb6df04df0f6f36b4b7a7ba38be35ad..9879e94e88f96aabe28395ff127f8ae5cb7be6f5 100644
--- a/boards/beagleplay/demos-and-tutorials/using-serial-console.rst
+++ b/boards/beagleplay/demos-and-tutorials/using-serial-console.rst
@@ -6,7 +6,7 @@ Using Serial Console
To see the board boot log and access your BeaglePlay's console you can connect a USB-UART
cable as depicted in the image below and use applications like ``tio`` to access the console.
-.. figure:: images/serial-debug-connection.jpg
+.. figure:: images/serial-debug-connection.*
:width: 1400
:alt: Serial debug (USB-UART) cable connection.
diff --git a/boards/beagleplay/images/OSHW_mark_US002174.png b/boards/beagleplay/images/OSHW_mark_US002174.png
deleted file mode 100644
index 6cf75dc41d5bdca1e2a0eacd68f5d9f983958131..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/OSHW_mark_US002174.png and /dev/null differ
diff --git a/boards/beagleplay/images/OSHW_mark_US002174.webp b/boards/beagleplay/images/OSHW_mark_US002174.webp
deleted file mode 100644
index 9f3a92c4b68ad802e0c4a170e6962ee4015b0bd6..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/OSHW_mark_US002174.webp and /dev/null differ
diff --git a/boards/beagleplay/images/am625.png b/boards/beagleplay/images/am625.png
deleted file mode 100644
index 4e1ffadc669114e2cd943d1346afae689069cb83..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/am625.png and /dev/null differ
diff --git a/boards/beagleplay/images/components-back.jpg b/boards/beagleplay/images/components-back.jpg
deleted file mode 100644
index 67034fbbd79b1c04887641f84f0be9d282a86815..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/components-back.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/components-front.jpg b/boards/beagleplay/images/components-front.jpg
deleted file mode 100644
index 1adcdf9f86c3fa0e81f31fdd02ac7838769e089f..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/components-front.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/dimensions.png b/boards/beagleplay/images/dimensions.png
deleted file mode 100644
index 10aa22ecf67522c1f7023099105b533df7d8f47e..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/dimensions.png and /dev/null differ
diff --git a/boards/beagleplay/images/dimensions.webp b/boards/beagleplay/images/dimensions.webp
new file mode 100644
index 0000000000000000000000000000000000000000..70ad187912d71967fb7a9c71fe7f7612622b265d
Binary files /dev/null and b/boards/beagleplay/images/dimensions.webp differ
diff --git a/boards/beagleplay/images/product-pictures/45back.webp b/boards/beagleplay/images/product-pictures/45back.webp
deleted file mode 100644
index d549c23d4566982f6c3346b65712b5c9329269e5..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/45back.webp and /dev/null differ
diff --git a/boards/beagleplay/images/product-pictures/45back74.jpg b/boards/beagleplay/images/product-pictures/45back74.jpg
deleted file mode 100644
index 8c8c5fe96358c0a1ff32b655797d87ec12687d1b..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/45back74.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/product-pictures/45back74.webp b/boards/beagleplay/images/product-pictures/45back74.webp
new file mode 100644
index 0000000000000000000000000000000000000000..e1887ac8c22eb1c08dc87aa4c3e1ff4e9e05dd9d
Binary files /dev/null and b/boards/beagleplay/images/product-pictures/45back74.webp differ
diff --git a/boards/beagleplay/images/product-pictures/45fontall.jpg b/boards/beagleplay/images/product-pictures/45fontall.jpg
deleted file mode 100644
index 7cc12c8108f1e4ff22bda788f8ddd4505af9910c..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/45fontall.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/product-pictures/45fontall.webp b/boards/beagleplay/images/product-pictures/45fontall.webp
new file mode 100644
index 0000000000000000000000000000000000000000..7bd37e725b9cd3ea41d8fd4e18aeac1497ee1af0
Binary files /dev/null and b/boards/beagleplay/images/product-pictures/45fontall.webp differ
diff --git a/boards/beagleplay/images/product-pictures/45front.jpg b/boards/beagleplay/images/product-pictures/45front.jpg
deleted file mode 100644
index 5284e088ba25c59b35c43657f74d06b2ae1fd1e7..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/45front.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/product-pictures/back.jpg b/boards/beagleplay/images/product-pictures/back.jpg
deleted file mode 100644
index 1a570ae8096d3496fa9f1e61135b64c2cd973e61..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/back.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/product-pictures/front.jpg b/boards/beagleplay/images/product-pictures/front.jpg
deleted file mode 100644
index 43eed3981b4ab3427b0f19f02a5432e6e5876396..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/product-pictures/front.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/side-dimensions.png b/boards/beagleplay/images/side-dimensions.png
deleted file mode 100644
index 42766a528b7ac631b4769aa9ca10f9961710d65c..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/side-dimensions.png and /dev/null differ
diff --git a/boards/beagleplay/images/side-dimensions.webp b/boards/beagleplay/images/side-dimensions.webp
new file mode 100644
index 0000000000000000000000000000000000000000..3769e426029f5b3aa2c39b2101b38644ce36c209
Binary files /dev/null and b/boards/beagleplay/images/side-dimensions.webp differ
diff --git a/boards/beagleplay/images/tethered-connection.jpg b/boards/beagleplay/images/tethered-connection.jpg
deleted file mode 100644
index 1d9a5d683f0af50a703005f483d0c0ffa8a38b8f..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/tethered-connection.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/tethered-connection.webp b/boards/beagleplay/images/tethered-connection.webp
new file mode 100644
index 0000000000000000000000000000000000000000..099588b56221190bf5d8bf2dd517423606beaa10
Binary files /dev/null and b/boards/beagleplay/images/tethered-connection.webp differ
diff --git a/boards/beagleplay/images/vscode.png b/boards/beagleplay/images/vscode.png
deleted file mode 100644
index a4b3109678dcd75f810d9c4d3396bbd680ca58ae..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/vscode.png and /dev/null differ
diff --git a/boards/beagleplay/images/vscode.webp b/boards/beagleplay/images/vscode.webp
new file mode 100644
index 0000000000000000000000000000000000000000..37febd2848dfb503225f569876db0bedb9e9b35a
Binary files /dev/null and b/boards/beagleplay/images/vscode.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step1a.jpg b/boards/beagleplay/images/wpa_cli_step1a.jpg
deleted file mode 100644
index 386f4f4a01b67fb0cb4242a7fde3e51568efc1ca..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step1a.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step1a.webp b/boards/beagleplay/images/wpa_cli_step1a.webp
new file mode 100644
index 0000000000000000000000000000000000000000..5ea1810ea54f811dc1109f7eead425b025eb10f4
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step1a.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step1b.jpg b/boards/beagleplay/images/wpa_cli_step1b.jpg
deleted file mode 100644
index 0efbad6130a7fb53acb39965f49f828e5cf40bbe..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step1b.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step1b.webp b/boards/beagleplay/images/wpa_cli_step1b.webp
new file mode 100644
index 0000000000000000000000000000000000000000..cee3d82e47071aff2c0b5c77e0886df1caeceb53
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step1b.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step2a.jpg b/boards/beagleplay/images/wpa_cli_step2a.jpg
deleted file mode 100644
index 1e0d547ca6f7db8ceecbc67a3216f7de2d05def9..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step2a.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step2a.webp b/boards/beagleplay/images/wpa_cli_step2a.webp
new file mode 100644
index 0000000000000000000000000000000000000000..aefed683d2382eb28e662a7b07c43d59e31a66c4
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step2a.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step2b.jpg b/boards/beagleplay/images/wpa_cli_step2b.jpg
deleted file mode 100644
index 81e076e93352ced2243911c0b9e104ae267cc1cc..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step2b.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step2b.webp b/boards/beagleplay/images/wpa_cli_step2b.webp
new file mode 100644
index 0000000000000000000000000000000000000000..9271d96dba7332f6a4e9ce5d9617df50c9e02987
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step2b.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step2c.jpg b/boards/beagleplay/images/wpa_cli_step2c.jpg
deleted file mode 100644
index a11331b2781a065c6a61ee4d4014860978a87edc..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step2c.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step2c.webp b/boards/beagleplay/images/wpa_cli_step2c.webp
new file mode 100644
index 0000000000000000000000000000000000000000..a123104fc233e32886f22bb61382864a04d2d4ae
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step2c.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step3a.jpg b/boards/beagleplay/images/wpa_cli_step3a.jpg
deleted file mode 100644
index 249729dffe528e372092365bdcb8a369e210f615..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step3a.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step3a.webp b/boards/beagleplay/images/wpa_cli_step3a.webp
new file mode 100644
index 0000000000000000000000000000000000000000..9f42393ec064d863c3438232501cb36de20d1819
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step3a.webp differ
diff --git a/boards/beagleplay/images/wpa_cli_step3b.jpg b/boards/beagleplay/images/wpa_cli_step3b.jpg
deleted file mode 100644
index 7ce3d5aaff7d85dac5dcce748a716604b6097bdd..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_cli_step3b.jpg and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_cli_step3b.webp b/boards/beagleplay/images/wpa_cli_step3b.webp
new file mode 100644
index 0000000000000000000000000000000000000000..c2f546399ab520773c6cd5c6d573f0fa737db6df
Binary files /dev/null and b/boards/beagleplay/images/wpa_cli_step3b.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step1a.png b/boards/beagleplay/images/wpa_gui_step1a.png
deleted file mode 100644
index 6ea7ec7b845fb2f1b17b882004b5f4739e0ce60d..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step1a.png and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_gui_step1a.webp b/boards/beagleplay/images/wpa_gui_step1a.webp
new file mode 100644
index 0000000000000000000000000000000000000000..608554309ebd07d33a9c827bc0e6c53fb7b5875e
Binary files /dev/null and b/boards/beagleplay/images/wpa_gui_step1a.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step1b.png b/boards/beagleplay/images/wpa_gui_step1b.png
deleted file mode 100644
index e4614cb9622385b0dfa6193feada246fcfd36c6f..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step1b.png and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_gui_step1b.webp b/boards/beagleplay/images/wpa_gui_step1b.webp
new file mode 100644
index 0000000000000000000000000000000000000000..f7bc2f0d84280b3c2b4734d9c7e5c3ce9fc314c6
Binary files /dev/null and b/boards/beagleplay/images/wpa_gui_step1b.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step2.png b/boards/beagleplay/images/wpa_gui_step2.png
deleted file mode 100644
index 4a594d12b6efe55529761fc5e302771d5529642d..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step2.png and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_gui_step2.webp b/boards/beagleplay/images/wpa_gui_step2.webp
new file mode 100644
index 0000000000000000000000000000000000000000..6bbaffd2a634dbc14db6006921b0d6c071405ed5
Binary files /dev/null and b/boards/beagleplay/images/wpa_gui_step2.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step3a.png b/boards/beagleplay/images/wpa_gui_step3a.png
deleted file mode 100644
index 60ecb250586ec0face481cd997f9582665a8b4e5..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step3a.png and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_gui_step3a.webp b/boards/beagleplay/images/wpa_gui_step3a.webp
new file mode 100644
index 0000000000000000000000000000000000000000..910cef7b3736f8ee65c39421178c8bc67badfc34
Binary files /dev/null and b/boards/beagleplay/images/wpa_gui_step3a.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step3b.png b/boards/beagleplay/images/wpa_gui_step3b.png
deleted file mode 100644
index eea964f302e709ba294eea0c3f93a38d9ed3eb70..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step3b.png and /dev/null differ
diff --git a/boards/beagleplay/images/wpa_gui_step3b.webp b/boards/beagleplay/images/wpa_gui_step3b.webp
new file mode 100644
index 0000000000000000000000000000000000000000..6cfcf0f8713ad276222c65d8c9e8c9594674d51e
Binary files /dev/null and b/boards/beagleplay/images/wpa_gui_step3b.webp differ
diff --git a/boards/beagleplay/images/wpa_gui_step3c.jpg b/boards/beagleplay/images/wpa_gui_step3c.jpg
deleted file mode 100644
index 2e62f3fe2b599e2d55c7d03082564c595943de8d..0000000000000000000000000000000000000000
Binary files a/boards/beagleplay/images/wpa_gui_step3c.jpg and /dev/null differ
diff --git a/boards/beaglev/ahead/02-quick-start.rst b/boards/beaglev/ahead/02-quick-start.rst
index 31db59b5e83092faf1c3e0a71bf4c6cbab69aa4d..a4fa41dcb718b738a3c1f3263a10dc03610b877e 100644
--- a/boards/beaglev/ahead/02-quick-start.rst
+++ b/boards/beaglev/ahead/02-quick-start.rst
@@ -21,25 +21,10 @@ When you purchase a brand new BeagleV Ahead, In the box you'll get:
Unboxing
*********
-.. only:: latex
-
- .. image:: https://img.youtube.com/vi/SVC9peUUzE0/maxresdefault.jpg
- :alt: BeagleV Ahead Unboxing YouTube video
- :width: 1280
- :target: https://www.youtube.com/watch?v=SVC9peUUzE0
-
-.. only:: html
-
- .. raw:: html
-
- <iframe style="display: block; margin: auto;" width="1280" height="720" style="align:center"
- src="https://www.youtube.com/embed/SVC9peUUzE0"
- title="YouTube video player"
- frameborder="0"
- allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
- allowfullscreen>
- </iframe>
-
+.. youtube:: SVC9peUUzE0
+ :width: 1280
+ :height: 720
+ :align: center
Antenna guide
*************
diff --git a/boards/beaglev/fire/02-quick-start.rst b/boards/beaglev/fire/02-quick-start.rst
index 52e9074b909fe052f70566744ae2837c872c9126..dc4c2722134f0ae402d9b0b105f4038fe60dcb2f 100644
--- a/boards/beaglev/fire/02-quick-start.rst
+++ b/boards/beaglev/fire/02-quick-start.rst
@@ -13,24 +13,10 @@ When you purchase a brand new BeagleV-Fire, In the box you'll get:
Unboxing
*********
-.. only:: latex
-
- .. image:: https://img.youtube.com/vi/5cylv1R-1mc/maxresdefault.jpg
- :alt: BeagleV Ahead Unboxing YouTube video
- :width: 1280
- :target: https://www.youtube.com/watch?v=5cylv1R-1mc
-
-.. only:: html
-
- .. raw:: html
-
- <iframe style="display: block; margin: auto;" width="1280" height="720" style="align:center"
- src="https://www.youtube.com/embed/5cylv1R-1mc"
- title="YouTube video player"
- frameborder="0"
- allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
- allowfullscreen>
- </iframe>
+.. youtube:: 5cylv1R-1mc
+ :align: center
+ :width: 1280
+ :height: 720
Tethering to PC
diff --git a/conf.py b/conf.py
index db24966b6de30df34615dc170c26255990eb5886..ddbe82e86a6cc4c742eccd9f9eee7e39bef143ae 100644
--- a/conf.py
+++ b/conf.py
@@ -41,6 +41,7 @@ extensions = [
"sphinx_tabs.tabs",
"breathe",
"sphinx_copybutton",
+ "sphinxcontrib.youtube",
]
#graphviz_output_format = 'svg'
@@ -229,6 +230,9 @@ html_context = {
"gitlab_repo": gitlab_repo,
"gitlab_version": gitlab_version,
"doc_path": "",
+ #"use_edit_page_button": True,
+ #"edit_page_provider_name": "OpenBeagle",
+ #"edit_page_url_template": "https://openbeagle.org/XXXX/{{ file_name }}",
"conf_py_path": "",
"show_license": True,
"pages_url": pages_url,
@@ -240,8 +244,8 @@ html_context = {
"edit_page_provider_name": "OpenBeagle",
"my_vcs_site": "https://openbeagle.org/gsoc/gsoc.beagleboard.io/-/edit/main/",
"reference_links": {
- "About": "https://beagleboard.org/about",
- "Donate": "https://beagleboard.org/donate",
+ "About": "https://www.beagleboard.org/about",
+ "Donate": "https://www.beagleboard.org/donate",
"FAQ": "https://forum.beagleboard.org/c/faq"
}
}
diff --git a/gitlab-build.sh b/gitlab-build.sh
index 02d0c00785b985ce6d7cf4da5d7abee81eb166c0..6518dbd6a1100c103c45115abf24a5a5391e78b6 100755
--- a/gitlab-build.sh
+++ b/gitlab-build.sh
@@ -6,6 +6,8 @@ export PATCHLEVEL=$(date +%Y%m%d)
export VERSION_TWEAK=$(( $(date "+10#%H * 60 + 10#%M") ))
function do_build() {
+ echo "**** Updating $PAGES_URL/$VER_DIR: $1 ****"
+
cat << EOF > PAGES
PAGES_URL = $PAGES_URL
PAGES_SLUG = $PAGES_SLUG
@@ -23,8 +25,16 @@ VERSION_TWEAK = $VERSION_TWEAK
EXTRAVERSION = $EXTRAVERSION
EOF
- mkdir -p public
- cat <<HERE > public/index.html
+ echo "**** make librobotcontrol xml ****"
+ if [ -e projects/librobotcontrol/docs ] ; then
+ cd projects/librobotcontrol/docs
+ doxygen
+ cd ../../..
+ fi
+
+ if [ "x$1" == "xhtml" ]; then
+ mkdir -p public/html
+ cat <<HERE > public/html/redir.html
<!DOCTYPE html>
<html>
<head>
@@ -36,60 +46,41 @@ EOF
</html>
HERE
- echo "**** Updating $PAGES_URL/$VER_DIR ****"
-
- echo "**** env ****"
- env
-
- echo "**** make clean ****"
- # Clean build directory
- make clean BUILDDIR=public/$VER_DIR
-
- echo "**** make librobotcontrol xml ****"
- if [ -e projects/librobotcontrol/docs ] ; then
- cd projects/librobotcontrol/docs
- doxygen
- cd ../../..
+ echo "**** make html ****"
+ # Build HTML
+ make html BUILDDIR=public
fi
- echo "**** make html ****"
- # Build and serve HTML
- make html BUILDDIR=public/$VER_DIR
- mv public/$VER_DIR/html/* public/$VER_DIR/
-
- echo "**** make latexpdf ****"
- # Build, optimize, and serve PDF
- make latexpdf BUILDDIR=public/$VER_DIR
+ if [ "x$1" == "xpdf" ]; then
+ echo "**** make latexpdf ****"
+ # Build, optimize, and serve PDF
+ make latexpdf BUILDDIR=public
- echo "**** pdfcpu ****"
- if [ "x${CI_RUNNER_EXECUTABLE_ARCH}" == "xlinux/arm64" ] ; then
- echo "**** check and install pdfcpu ****"
- if [ ! -f /usr/local/bin/pdfcpu ] ; then
- wget https://github.com/pdfcpu/pdfcpu/releases/download/v0.4.0/pdfcpu_0.4.0_Linux_arm64.tar.xz
- tar xf pdfcpu_0.4.0_Linux_arm64.tar.xz
- mv -v pdfcpu_0.4.0_Linux_arm64/pdfcpu /usr/local/bin/
- fi
- /usr/local/bin/pdfcpu version
- du -sh public/$VER_DIR/latex/beagleboard-docs.pdf
- /usr/local/bin/pdfcpu optimize public/$VER_DIR/latex/beagleboard-docs.pdf
- du -sh public/$VER_DIR/latex/beagleboard-docs.pdf
- else
+ echo "**** pdfcpu ****"
pdfcpu version
- pdfcpu optimize public/$VER_DIR/latex/beagleboard-docs.pdf
+ pdfcpu optimize public/latex/beagleboard-docs.pdf
+
+ echo "**** cleanup ****"
+ mkdir -p public/pdf
+ mv public/latex/beagleboard-docs.pdf public/pdf
+ rm -rf public/doctrees
+ rm -rf public/latex
fi
- mv public/$VER_DIR/latex/beagleboard-docs.pdf public/$VER_DIR/
- echo "**** cleanup ****"
- # Cleanup
- rm -rf public/$VER_DIR/doctrees
- rm -rf public/$VER_DIR/latex
+ if [ "x$1" == "xpublish" ]; then
+ # Move files
+ mkdir -p public/$VER_DIR/
+ mv public/html/redir.html public/index.html
+ mv public/html/* public/$VER_DIR/
+ mv public/pdf/beagleboard-docs.pdf public/$VER_DIR/
- # Update docs.beagleboard.org
- if [ "$CI_COMMIT_TAG" != "" ]; then
- if [ "$VER_DIR" = "latest" ]; then
- cp public/index.html /var/www/docs
+ # Update docs.beagleboard.org
+ if [ "$CI_COMMIT_TAG" != "" ]; then
+ if [ "$VER_DIR" = "latest" ]; then
+ cp public/index.html /var/www/docs
+ fi
+ rsync -v -a --delete public/$VER_DIR/. /var/www/docs/$VER_DIR
fi
- rsync -v -a --delete public/$VER_DIR/. /var/www/docs/$VER_DIR
fi
}
@@ -104,7 +95,7 @@ if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then
export VERSION_MAJOR=$VER_LATEST_MAJOR
export VERSION_MINOR=$VER_LATEST_MINOR
export EXTRAVERSION=$VER_LATEST_EXTRA
- do_build
+ do_build $1
elif [ "$CI_COMMIT_BRANCH" != "" ]; then
export VER_DIR=$CI_COMMIT_BRANCH
export PAGES_URL=$CI_PAGES_URL
@@ -117,7 +108,7 @@ elif [ "$CI_COMMIT_BRANCH" != "" ]; then
export VERSION_MAJOR=${BRANCH_VER[0]}
export VERSION_MINOR=${BRANCH_VER[1]}
export EXTRAVERSION=wip
- do_build
+ do_build $1
elif [ "$CI_COMMIT_TAG" != "" ]; then
export TAG_SPLIT=($(echo $CI_COMMIT_TAG | tr "-" "\n"))
export TAG_VER=($(echo ${TAG_SPLIT[0]} | tr "." "\n"))
@@ -139,10 +130,11 @@ elif [ "$CI_COMMIT_TAG" != "" ]; then
export PAGES_SLUG=$GIT_BRANCH
fi
export SPHINXOPTS="-D todo_include_todos=0"
- do_build
+ do_build $1
else
echo "***** Not on a branch or tag *****"
fi
+echo "**** env ****"
env
diff --git a/intro/beagle101/arm.rst b/intro/beagle101/arm.rst
new file mode 100644
index 0000000000000000000000000000000000000000..88dd796aa064818d18fd073c63990f43146125fb
--- /dev/null
+++ b/intro/beagle101/arm.rst
@@ -0,0 +1,6 @@
+.. _intro-arm:
+
+Introduction to Arm
+###################
+
+.. todo:: Place-holder for Arm tutorial
diff --git a/intro/beagle101/assembly.rst b/intro/beagle101/assembly.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3d846fc6be433c22cf09b824a82da810a6c4b1c5
--- /dev/null
+++ b/intro/beagle101/assembly.rst
@@ -0,0 +1,9 @@
+.. _intro-assembly:
+
+Introduction to Assembly Programming
+####################################
+
+Assembly programming is a programming style that is the most direct to the binary machine
+instructions a computer follows.
+
+.. todo:: Write assembly guide
diff --git a/intro/beagle101/basic-wiring.rst b/intro/beagle101/basic-wiring.rst
new file mode 100644
index 0000000000000000000000000000000000000000..356c683141b246b16af3fd7b7b07084481a85105
--- /dev/null
+++ b/intro/beagle101/basic-wiring.rst
@@ -0,0 +1,6 @@
+.. _intro-basic-wiring:
+
+Introduction to Wiring Electronics
+##################################
+
+.. todo:: Place-holder for electronics wiring tutorial
diff --git a/intro/beagle101/blinkLED.rst b/intro/beagle101/blinkLED.rst
index 1d66ddec45b4575021b970778d3284d3151d9e29..e50cf87ab2708e9511826a27cc70835c5605c575 100644
--- a/intro/beagle101/blinkLED.rst
+++ b/intro/beagle101/blinkLED.rst
@@ -3,8 +3,8 @@
.. _blinkLED:
-Blink LED
-#########
+Blink an LED
+############
The "Hello World!" of the embedded world is to blink an LED.
Here we'll show you how to do just that in three simple steps.
@@ -114,6 +114,8 @@ load up Linux. This is because all Beagles
to install an image on the Pocket) have built-in flash memory
that has the Debian distribution of Linux preinstalled.
+.. _intro-using-vs-code:
+
Using VS Code
**************
diff --git a/intro/beagle101/buildroot.rst b/intro/beagle101/buildroot.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f247e92192c33298702c249885b82f63c0d76c4d
--- /dev/null
+++ b/intro/beagle101/buildroot.rst
@@ -0,0 +1,6 @@
+.. _intro-buildroot:
+
+Introduction to Buildroot
+#########################
+
+.. todo:: Place-holder for Buildroot tutorial
diff --git a/intro/beagle101/c.rst b/intro/beagle101/c.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cac26db97ac2a6b4230af9bdacce206c471fc9d1
--- /dev/null
+++ b/intro/beagle101/c.rst
@@ -0,0 +1,74 @@
+.. _intro-c:
+
+Introduction to C
+#################
+
+.. todo:: Place-holder for tutorial on the C programming language
+
+The C programming language is powerful and flexible and sits at the heart of
+many key open source software projects, including :ref:`Linux <intro-linux>` and
+:ref:`Zephyr <intro-zephyr>`. While it is intimidating to many people, C holds a
+strong relevance in today's technology landscape and can be approached and learned
+by those without extensive previous computer knowledge.
+
+While there are many :ref:`resources <intro-c-resources>` for learning C, this article
+will focus primarily on learning C using Linux and specifically a Beagle running
+:ref:`Debian GNU/Linux <intro-debian>`. It is recommended to utilize on-line learning
+resources like `learn-c.org`_ to get familiarity with the language, then apply what you
+have learned on a Beagle to see it in real life.
+
+.. note::
+
+ Making the transition from on-line to in-person compilation and execution of your
+ code is critical to building and maintaining your understanding. You can never be
+ certain that an on-line service will always be available, so do yourself the favor
+ or transitioning your exercises and materials into your own possession as soon as
+ it makes sense for you.
+
+Why Learn C?
+************
+
+While C is an extremely popular programming language, popularity shouldn't necessarily be
+your top guide in choosing a programming language to learn. What are some of the best
+reasons to learn C?
+
+Provides Strong Foundation
+==========================
+
+Many other programming languages are very similar to C, like `Java`_, `Wiring`_ or `Rust`_,
+are direct extensions of C, namely `C++`_ and `C#`_, or are written in C themselves.
+Learning C will set you up well to learn many programming languages and the rationales
+behind them.
+
+Your First C Program
+********************
+
+:ref:`start-browse-to-beagle`
+
+:ref:`intro-using-vs-code`
+
+.. _intro-c-resources:
+
+Recommended Resources
+*********************
+
+* `C Programming Language, 2nd Edition <https://a.co/d/51eEGca>`_
+* `learn-c.org`_
+
+.. _C++:
+ https://en.wikipedia.org/wiki/C%2B%2B
+
+.. _Wiring:
+ https://en.wikipedia.org/wiki/Wiring_(software)
+
+.. _Java:
+ https://en.wikipedia.org/wiki/Java_(programming_language)
+
+.. _Rust:
+ https://en.wikipedia.org/wiki/Rust_(programming_language)
+
+.. _learn-c.org:
+ https://learn-c.org
+
+.. _C#:
+ https://en.wikipedia.org/wiki/C_Sharp_%28programming_language%29
diff --git a/intro/beagle101/debian.rst b/intro/beagle101/debian.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7c09b80a615783c203ad6f02f6fac84816219c32
--- /dev/null
+++ b/intro/beagle101/debian.rst
@@ -0,0 +1,6 @@
+.. _intro-debian:
+
+Introduction to Debian
+######################
+
+.. todo:: Place-holder for Debian tutorial
diff --git a/intro/beagle101/device-tree.rst b/intro/beagle101/device-tree.rst
new file mode 100644
index 0000000000000000000000000000000000000000..fbd65ea017bafb289fa4411d4c2b64d0b53e271c
--- /dev/null
+++ b/intro/beagle101/device-tree.rst
@@ -0,0 +1,6 @@
+.. _intro-device-tree:
+
+Introduction to Device Tree
+###########################
+
+.. todo:: Place-holder for Device Tree tutorial
diff --git a/intro/beagle101/embedded-serial.rst b/intro/beagle101/embedded-serial.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8fe802882b09586b81d65530479821a2e8f9400a
--- /dev/null
+++ b/intro/beagle101/embedded-serial.rst
@@ -0,0 +1,6 @@
+.. _intro-embedded-serial:
+
+Introduction to Embedded Serial Interfaces
+##########################################
+
+.. todo:: Place-holder for embedded serial interfaces tutorial
diff --git a/intro/beagle101/fpga.rst b/intro/beagle101/fpga.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8dc611905548431365cd8e00fd12176b9a63cc06
--- /dev/null
+++ b/intro/beagle101/fpga.rst
@@ -0,0 +1,6 @@
+.. _intro-fpga:
+
+Introduction to Field Programmable Gate Arrays (FPGAs)
+######################################################
+
+.. todo:: Place-holder for FPGA tutorial
diff --git a/intro/beagle101/index.rst b/intro/beagle101/index.rst
index d3a57d6606aa1ce89aff08699adbf55051447856..51181c51a4dd638764c2ed4cd0ff5c40c5956bea 100644
--- a/intro/beagle101/index.rst
+++ b/intro/beagle101/index.rst
@@ -3,19 +3,53 @@
An Introduction to Beagles
##########################
+The most common path to using a Beagle is to use a body of open source software. The
+primary open source targets supported by the BeagleBoard.org community are:
+
+* :ref:`intro-beagle-linux` and
+* :ref:`intro-beagle-zephyr`.
+
+Many other paths are possible, but, if you don't already have a path, these are the
+ones to typically go down.
+
+If you are new to embedded systems in general, you might consider starting at:
+
+* :ref:`intro-embedded-systems`
+
.. toctree::
:maxdepth: 1
:hidden:
blinkLED
- linux
+ c
+ assembly
+ verilog
+ basic-wiring
+ embedded-serial
qwiic-stemma-grove-addons
+ motors
+ zephyr
+ linux
+ device-tree
+ fpga
+ verification
+ arm
+ riscv
+ openbeagle-ci
+ buildroot
+ debian
+ wireless-communications
-Linux-enabled boards
-********************
+.. _intro-beagle-linux:
+
+Getting started with Linux
+**************************
Most Beagles have on-board flash preconfigured to run Linux. These resources will get you started quickly.
+Linux Basics
+============
+
* Get started at :ref:`blinkLED`.
* Learn to reset a board back to factory defaults and dive a bit deeper into the IDE at :ref:`beagleboard-getting-started`.
* Learn a bit about Linux at :ref:`intro-linux`.
@@ -23,21 +57,79 @@ Most Beagles have on-board flash preconfigured to run Linux. These resources wil
* Learn about using 3rd party I2C add-on boards at :ref:`qwiic_stemma_grove_addons`.
* Learn about using mikroBUS add-on boards at :ref:`beagleplay-mikrobus`.
* Learn about using Cape add-on boards at :ref:`capes`.
+* Learn about device tree at :ref:`intro-device-tree`.
* Read :ref:`bone-cook-book-home`.
* Read :ref:`pru-cookbook-home`.
* Find more books at https://www.beagleboard.org/books.
-Zephyr-enabled boards
-*********************
+More on Linux
+=============
+
+* :ref:`intro-buildroot`
+* :ref:`intro-debian`
+
+.. _intro-beagle-zephyr:
+
+Getting started with Zephyr
+***************************
Our Zephyr-enabled boards ship with a build of Micropython and, in the future, will also
ship with a BeagleConnect Greybus node service for quick, transparent access from any BeagleConnect
Greybus host enabled system.
+Zephyr Basics
+=============
+
+* Learn a bit about Zephyr at :ref:`intro-zephyr`
* See :ref:`beagleconnect-freedom-using-micropython` to get started quickly.
* See :ref:`beagleconnect-freedom-using-zephyr` to learn to setup the Zephyr SDK.
* See :ref:`beagleconnect-overview` to learn about BeagleConnect Greybus.
+.. _intro-embedded-systems:
+
+Getting started with embedded systems
+*************************************
+
+An embedded system is a computer designed not to look like a computer. That is, it
+is designed to work like an applicance, doing what you need when you need it, rather
+than sitting around trying to get your attention and begging to be told what to do.
+
+An embedded system is built around a computer, but adds additional sensors and
+actuators to do a task, like make toast or get you to work on time along using the
+freeway. We don't typically call these things computers. Instead, we call them "toasters"
+or "cars". At the heart of these machines is often a programmable computer, though it
+might not be programmable by *you*.
+
+At BeagleBoard.org, we seek to enable you to make embedded systems of your own, rather
+than relying on other people to make them for you. You could call it DIY, or do-it-yourself,
+but the reality is more DIT, or do-it-together. The skills and tools to build an embedded
+system are very complicated and the fundamental manufacturing tools are very expensive, so we
+need to work together to build even the simplest of embedded systems.
+
+Of course, there is nothing wrong with building a dumb toaster, it might even be preferred.
+However, if you are building a smart toaster, you might want it to obey you, rather than
+someone 50,000 km away.
+
+Embedded Systems Basics
+=======================
+
+Here are some basic skills to building an embedded system:
+
+* :ref:`intro-c`
+* :ref:`intro-assembly`
+* :ref:`intro-verilog`
+
+More on Embedded Systems
+========================
+
+Here are some more advanced topics around building an embedded system:
+
+* :ref:`intro-fpga`
+* :ref:`intro-verification`
+* :ref:`intro-arm`
+* :ref:`intro-riscv`
+* :ref:`intro-wireless-communications`
+
.. todo::
Make sure we have everything critical from https://beagleboard.github.io/bone101/Support/bone101/
diff --git a/intro/beagle101/linux.rst b/intro/beagle101/linux.rst
index f21cbeb598a8bb6525ad18295b4fbcf4aee98f9a..b46cdddc010ead10d7700e6894ab5480cda3c83a 100644
--- a/intro/beagle101/linux.rst
+++ b/intro/beagle101/linux.rst
@@ -1,7 +1,7 @@
.. _intro-linux:
-An Introduction to Linux
-########################
+Introduction to Linux
+#####################
This article seeks to give you some quick exploration of Linux. For a deeper training,
scroll down to :ref:`embedded-linux-training`.
diff --git a/intro/beagle101/motors.rst b/intro/beagle101/motors.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b3cd2c40bd046df37f8e0516fc093032bad4e1fd
--- /dev/null
+++ b/intro/beagle101/motors.rst
@@ -0,0 +1,6 @@
+.. _intro-motors:
+
+Introduction to Motors
+######################
+
+.. todo:: Place-holder for Motors tutorial
diff --git a/intro/beagle101/openbeagle-ci.rst b/intro/beagle101/openbeagle-ci.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7533ccafc02bd3e72cb585ce10b33849e8992703
--- /dev/null
+++ b/intro/beagle101/openbeagle-ci.rst
@@ -0,0 +1,6 @@
+.. _intro-openbeagle-ci:
+
+Introduction to OpenBeagle Continuous Integration (CI)
+######################################################
+
+.. todo:: Place-holder for OpenBeagle CI tutorial
diff --git a/intro/beagle101/riscv.rst b/intro/beagle101/riscv.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1233851d98784d195a8912470711cf2dd807f21c
--- /dev/null
+++ b/intro/beagle101/riscv.rst
@@ -0,0 +1,6 @@
+.. _intro-riscv:
+
+Introduction to RISC-V
+######################
+
+.. todo:: Place-holder for RISC-V tutorial
diff --git a/intro/beagle101/verification.rst b/intro/beagle101/verification.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bf0f06d14c04ff563ea18296ffcfa1cb66d286db
--- /dev/null
+++ b/intro/beagle101/verification.rst
@@ -0,0 +1,6 @@
+.. _intro-verification:
+
+Introduction to Verification
+############################
+
+.. todo:: Place-holder for verification tutorial
diff --git a/intro/beagle101/verilog.rst b/intro/beagle101/verilog.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0be06714a4f67959afdd2f694e6c8a5c806f4692
--- /dev/null
+++ b/intro/beagle101/verilog.rst
@@ -0,0 +1,6 @@
+.. _intro-verilog:
+
+Introduction to Verilog
+#######################
+
+.. todo:: Place-holder for tutorial on the Verilog programming language
diff --git a/intro/beagle101/wireless-communications.rst b/intro/beagle101/wireless-communications.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8243ba7b5c87e465cad7561888752498661de1d8
--- /dev/null
+++ b/intro/beagle101/wireless-communications.rst
@@ -0,0 +1,6 @@
+.. _intro-wireless-communications:
+
+Introduction to Wireless Communications
+#######################################
+
+.. todo:: Place-holder for Wireless Communications tutorial
diff --git a/intro/beagle101/zepyr.rst b/intro/beagle101/zepyr.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0ebf20011665bd3c01bcb8ef8c593de0c084ff90
--- /dev/null
+++ b/intro/beagle101/zepyr.rst
@@ -0,0 +1,6 @@
+.. _intro-zephyr:
+
+Introduction to Zephyr RTOS
+###########################
+
+.. todo:: Place-holder for Zephyr tutorial
diff --git a/intro/contribution/background.rst b/intro/contribution/background.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2883a7d671ca9a33c2b5fcd79e740963166205db
--- /dev/null
+++ b/intro/contribution/background.rst
@@ -0,0 +1,11 @@
+.. _contribution-background:
+
+What should I know before I get started?
+########################################
+
+The more you know about Linux and contributing to upstream projects, the better, but this knowledge isn't strictly required. Simply
+reading about contributing to Linux and upstream projects can help build your vocabulary in a meaningful way to help out. Learn about
+the skills required for Linux contributions in the :ref:`beagleboard-linux-upstream` section.
+
+The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask
+smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation.
diff --git a/intro/contribution/code-of-conduct.rst b/intro/contribution/code-of-conduct.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e0aeb40734f6cb34975293d83475676e28608c54
--- /dev/null
+++ b/intro/contribution/code-of-conduct.rst
@@ -0,0 +1,13 @@
+.. _code-of-conduct:
+
+Code of Conduct
+###############
+
+This project and everyone participating are governed by the same code of conduct.
+
+.. note::
+ Check out https://forum.beagleboard.org/faq as a starting place for our code of conduct.
+
+By participating, you are expected to
+uphold this code. Please report unacceptable behavior to
+contact one of our administrators or moderators on https://forum.beagleboard.org/about.
diff --git a/intro/contribution/faq.rst b/intro/contribution/faq.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8e8ef9459669c2d52a4fd3477d7b78af9b8b1fb9
--- /dev/null
+++ b/intro/contribution/faq.rst
@@ -0,0 +1,9 @@
+.. _contribution-faq:
+
+Frequently Asked Questions
+##########################
+
+Please refer to the technical and contribution frequently asked questions pages before posting any of your own questions. Please
+feel encouraged to ask follow-up questions if any of the answers are not clear enough.
+
+* `Frequently asked questions contribution category on the BeagleBoard.org Forum <https://forum.beagleboard.org/c/faq>`__
diff --git a/intro/contribution/git-usage.rst b/intro/contribution/git-usage.rst
index 8b9adff1abab830770c4a48e631f9daaddb1ed83..ccd6a5396697c691585cc45e0cfc092024fb79f5 100644
--- a/intro/contribution/git-usage.rst
+++ b/intro/contribution/git-usage.rst
@@ -4,55 +4,52 @@ Git Usage
#########
.. note::
- For detailed information on Git and Gitlab checkout the official
- `Git and GitLab <https://openbeagle.org/help#git-and-gitlab>`_
- help page. Also, for good GitLab workflow you can checkout the
- `Introduction to GitLab Flow (FREE) <https://openbeagle.org/help/topics/gitlab_flow.md>`_ page.
-These are (draft) general guidelines taken from
-`BioPython project <https://biopython.org/wiki/GitUsage>`_
-to be used for BeagleBoard development using
-git. We're still working on the finer details.
+ For detailed information on Git and OpenBeagle GitLab checkout the official
+ `help page <https://openbeagle.org/help#git-and-gitlab>`_.
-This document is meant as an outline of the way BeagleBoard projects are developed.
+.. note::
+
+ Most of these guidelines were taken from the
+ `BioPython project <https://biopython.org/wiki/GitUsage>`_
+ to be used for BeagleBoard Docs (and other OpenBeagle-hosted project) development using
+ ``git``. Please provide feedback via the
+ `site-feedback category on our forum <https://forum.beagleboard.org/c/site-feedback>`_.
+
+This document is meant as an outline of the way the BeagleBoard Docs project is developed.
It should include all essential technical information as well as typical
procedures and usage scenarios. It should be helpful for core
-developers, potential code contributors, testers and everybody
-interested in BeagleBoard code.
-
-.. note:: This version is an unofficial draft and is subject to change.
+developers, potential documentation contributors, testers and everybody
+interested in BeagleBoard Docs and other BeagleBoard projects.
Relevance
**********
-This page is about actually using git for tracking changes.
+This page is about using ``git`` for tracking and submitting changes.
If you have found a problem with any BeagleBoard project, and think you know how to
-fix it, then we suggest following the simple route of filing a
-bug and describe your fix. Ideally, you would upload a patch file showing the differences
+fix it, then we suggest following the simple route of filing an
+`issue <https://openbeagle.org/help/user/project/issues/index.md>`_ and describe
+your fix. Ideally, you would upload a patch file showing the differences
between the latest version of BeagleBoard project (from our repository) and your
-modified version. Working with the command line tools *diff* and *patch*
+modified version. Working with the command line tools ``diff`` and ``patch``
is a very useful skill to have, and is almost a precursor to working
with a version control system.
-
-Technicalities
-****************
-
-This section describes technical introduction into git usage including
-required software and integration with GitLab. If you want to start
-contributing to BeagleBoard, you definitely need to install git and learn
-how to obtain a branch of the BeagleBoard project you want to contribute.
+This page provides a technical introduction into ``git`` usage including
+required software and integration with OpenBeagle. If you want to start
+contributing to BeagleBoard projects, you definitely need to install ``git`` and learn
+how to obtain a branch of the OpenBeagle project to which you want to contribute.
If you want to share your changes easily with others, you should also
-sign up for a `OpenBeagle (BeagleBoard GitLab) <https://openbeagle.org/users/sign_up>`_
+sign up for an `OpenBeagle (BeagleBoard Gitlab) <https://openbeagle.org/users/sign_up>`_
account and read the corresponding section of the manual. Finally, if you are
-engaged in one of the collaborations on experimental BeagleBoard modules,
+engaged in one of the collaborations on experimental BeagleBoard projects,
you should look also into code review and branch merging.
-Installing Git
-***************
+Installing ``git``
+********************
-You will need to install Git on your computer. `Git <http://git-scm.com/>`_
+You will need to install ``git`` on your computer. `git <http://git-scm.com/>`_
is available for all major operating systems. Please use the appropriate
installation method as described below.
@@ -60,30 +57,29 @@ installation method as described below.
.. group-tab:: Linux
- Git is now packaged in all major Linux distributions, you should find it
+ ``git`` is now packaged in all major Linux distributions. You should find it
in your package manager.
**Ubuntu/Debian**
- You can install Git from the `git-core` package. e.g.,
+ You can install ``git`` from the `git-core` package. e.g.,
- .. code-block::
+ .. code-block:: shell
sudo apt-get install git-core
-
You'll probably also want to install the following packages: `gitk`,
`git-gui`, and `git-doc`
**Redhat/Fedora/Mandriva**
- git is also packaged in rpm-based linux distributions.
+ ``git`` is also packaged in rpm-based linux distributions.
- .. code-block::
+ .. code-block:: shell
dnf install gitk
- should do the trick for you in any recent fedora/mandriva or
+ should do the trick for you in any recent Fedora/Mandriva or
derivatives
.. group-tab:: Mac OS X
@@ -93,75 +89,88 @@ installation method as described below.
.. group-tab:: Windows
+ .. note::
+
+ It is worthwhile to consider using Linux at least inside of a virtual machine (VM).
+
Download the official installers from
`Windows installers <https://git-scm.com/download/win>`_
-Testing your git installation
-******************************
+Testing your ``git`` installation
+**********************************
If your installation succeeded, you should be able to run
-
.. code-block:: console
$ git --help
-in a console window to obtain information on git usage. If this fails, you should refer to git
-`documentation <https://git-scm.com/doc>`_ for troubleshooting.
+in a console window to obtain information on git usage. If this fails,
+you should refer to
+`official git documentation <https://git-scm.com/doc>`_ for troubleshooting.
-Creating a OpenBeagle account (Optional)
-****************************************
+Creating an OpenBeagle account (optional)
+******************************************
-Once you have Git installed on your machine, you can obtain the code and
-start developing. Since the code is hosted at OpenBeagle, however, you may
+.. note::
+
+ `OpenBeagle <https://openbeagle.org>`_ runs an open source instance of
+ `GitLab Community Edition <https://about.gitlab.com/>`_.
+
+Once you have ``git`` installed on your machine, you can obtain the code and
+start developing. Since the code is hosted by OpenBeagle, however, you may
wish to take advantage of the site's offered features by signing up for
-a OpenBeagle account. While a OpenBeagle account is completely optional and not
-required for obtaining the BeagleBoard code or participating in
-development, a OpenBeagle account will enable all other BeagleBoard developers
+an OpenBeagle account. While an OpenBeagle account is completely optional and not
+required for obtaining the BeagleBoard Docs code or participating in
+development, an OpenBeagle account will enable all other BeagleBoard Docs developers
to track (and review) your changes to the code base, and will help you
track other developers' contributions. This fosters a social,
collaborative environment for the BeagleBoard community.
-If you don't already have a OpenBeagle account, you can create one
-`here <https://openbeagle.org>`_.
+If you don't already have an OpenBeagle account, you can create one
+`here <https://openbeagle.org/users/sign_up>`_.
Once you have created your account, upload an SSH public key by clicking
-on `SSH and GPG keys <https://openbeagle.org/-/profile/keys>`_ after logging in. For more
+on `SSH and GPG keys <https://openbeagle.org/-/profile/keys>` after logging in. For more
information on generating and uploading an SSH public key, see `this
-GitLab guide <https://docs.gitlab.com/ee/user/ssh.html>`_.
+OpenBeagle guide on SSH keys <https://openbeagle.org/help/user/ssh.html>`_.
Working with the source code
******************************
-In order to start working with the BeagleBoard source code, you need to
-obtain a local clone of our git repository. In git, this means you will
-in fact obtain a complete clone of our git repository along with the
+In order to start working with the BeagleBoard Docs source code, you need to
+obtain a local clone of our ``git`` repository. In ``git``, this means you will
+in fact obtain a complete clone of our ``git`` repository along with the
full version history. Thanks to compression, this is not much bigger
than a single copy of the tree, but you need to accept a small overhead
in terms of disk space.
-There are, roughly speaking, two ways of getting the source code tree
-onto your machine: by simply "cloning" the repository, or by "forking"
-the repository on GitLab. They're not that different, in fact both will
-result in a directory on your machine containing a full copy of the
-repository. However, if you have a GitLab account, you can make your
-repository a public branch of the project. If you do so, other people
+There are, roughly speaking, two ways of getting your own version of the source code tree:
+
+1. by simply "cloning" the repository to your own computer,
+
+2. or by "forking" the repository on OpenBeagle.
+
+They're not that different, in fact both will
+result in a directory containing a customizable full copy of the
+repository. However, if you have a OpenBeagle account, you can make your
+repository a publicly visible branch of the project. If you do so, other people
will be able to easily review your code, make their own branches from it
or merge it back to the trunk.
-Using branches on GitLab is the preferred way to work on new features
-for BeagleBoard, so it's useful to learn it and use it even if you think
+Using branches on OpenBeagle is the preferred way to work on updates to
+BeagleBoard Docs, so it's useful to learn it and use it even if you think
your changes are not for immediate inclusion into the main trunk of
-BeagleBoard. But even if you decide not to use GitLab, you can always
-change this later (using the .git/config file in your branch.) For
+BeagleBoard Docs. But even if you decide not to use OpenBeagle, you can always
+change this later using the ``.git/config`` file in your clone. For
simplicity, we describe these two possibilities separately.
-Cloning repository directly
-*****************************
+Cloning BeagleBoard Docs directly
+==================================
-Getting a copy of the repository (called "cloning" in Git terminology)
-without GitLab account is very simple:
+Getting a copy of the repository (called "cloning" in ``git`` terminology)
+without an OpenBeagle account is very simple:
-.. code-block:: bash
+.. code-block:: shell
git clone https://openbeagle.org/docs/docs.beagleboard.io.git
@@ -172,59 +181,63 @@ this local copy (although we advise you to use named branches for this,
and keep the main branch in sync with the official BeagleBoard code).
If you want other people to see your changes, however, you must publish
-your repository to a public server yourself (e.g. on GitLab).
+your repository to a public server yourself (e.g. OpenBeagle, Github, GitLab).
+
+Forking BeagleBoard with your OpenBeagle account
+=================================================
+
+.. todo::
-Forking BeagleBoard with your GitLab account
-**********************************************
+ We need to describe how to use the "Web IDE" to work with OpenBeagle respositories.
-If you are logged in to GitLab, you can go to the BeagleBoard Docs repository page:
+If you are logged in to OpenBeagle, you can go to the BeagleBoard Docs repository
+page:
-https://openbeagle.org/docs/docs.beagleboard.io/-/tree/main
+https://openbeagle.org/docs/docs.beagleboard.io
-and click on a button named 'Fork'. This will create a fork (basically a
-copy) of the official BeagleBoard repository, publicly viewable on GitLab,
+and click on the button named 'Fork'. This will create a fork (basically a
+copy) of the official BeagleBoard Docs repository, publicly viewable on OpenBeagle,
but listed under your personal account. It should be visible under a URL
that looks like this:
-https://openbeagle.org/yourusername/docs.beagleboard.io/
+https://openbeagle.org/yourusername/docs.beagleboard.io
-Since your new BeagleBoard repository is publicly visible, it's considered
+Since your new BeagleBoard Docs repository is publicly visible, it's considered
good practice to change the description and homepage fields to something
meaningful (i.e. different from the ones copied from the official
repository).
If you haven't done so already, setup an SSH key and `upload it to
-gitlab <https://docs.gitlab.com/ee/user/ssh.html>`_ for
+OpenBeagle <https://openbeagle.org/help/user/ssh.html>`_ for
authentication.
-Now, assuming that you have git installed on your computer, execute the
+Now, assuming that you have ``git`` installed on your computer, execute the
following commands locally on your machine. This "url" is given on the
-GitLab page for your repository (if you are logged in):
+OpenBeagle page for your repository (if you are logged in):
-.. code-block:: bash
+.. code-block:: shell
- git clone https://openbeagle.org/yourusername/docs.beagleboard.io.git
+ git clone git@openbeagle.org:yourusername/docs.beagleboard.io.git
-Where `yourusername`, not surprisingly, stands for your GitLab username.
+Where `yourusername`, not surprisingly, stands for your OpenBeagle username.
You have just created a local copy of the BeagleBoard Docs repository on your
machine.
You may want to also link your branch with the official distribution
(see below on how to keep your copy in sync):
-.. code-block:: bash
+.. code-block:: shell
- git remote add upstream https://openbeagle.org/docs/docs.beagleboard.io/
+ git remote add upstream https://openbeagle.org/docs/docs.beagleboard.io
If you haven't already done so, tell git your name and the email address
-you are using on GitLab (so that your commits get matched up to your
-GitLab account). For example,
+you are using on OpenBeagle (so that your commits get matched up to your
+OpenBeagle account). For example,
-.. code-block:: bash
+.. code-block:: shell
git config --global user.name "David Jones" config --global user.email "d.jones@example.com"
-
Making changes locally
***********************
@@ -236,50 +249,50 @@ better to manage and document.
First of all, create a new branch to make some changes in, and switch to
it:
-.. code-block:: bash
+.. code-block:: shell
- git branch demo-branch checkout demo-branch
+ git checkout -b demo-branch
To check which branch you are on, use:
-.. code-block:: bash
+.. code-block:: shell
git branch
-Let us assume you've made changes to the file beaglebone-black/ch01.rst Try this:
+Let us assume you've made changes to the file boards/beagleplay/01-introduction.rst Try this:
-.. code-block:: bash
+.. code-block:: shell
git status
So commit this change you first need to explicitly add this file to your
change-set:
-.. code-block:: bash
+.. code-block:: shell
- git add beaglebone-black/ch01.rst
+ git add boards/beagleplay/01-introduction.rst
and now you commit:
-.. code-block:: bash
+.. code-block:: shell
- git commit -m "added updates X in BeagleBone Black ch01"
+ git commit -m "added updates X in BeaglePlay introduction"
-Your commits in Git are local, i.e. they affect only your working branch
-on your computer, and not the whole BeagleBoard tree or even your fork on
-GitLab. You don't need an internet connection to commit, so you can do
+Your commits in ``git`` are local, i.e. they affect only your working branch
+on your computer, and not the whole BeagleBoard Docs tree or even your fork on
+OpenBeagle. You don't need an internet connection to commit, so you can do
it very often.
-Pushing changes to GitLab
-**************************
+Pushing changes to OpenBeagle
+******************************
-If you are using GitLab, and you are working on a clone of your own
+If you are using OpenBeagle, and you are working on a clone of your own
branch, you can very easily make your changes available for others.
Once you think your changes are stable and should be reviewed by others,
-you can push your changes back to the GitLab server:
+you can push your changes back to the OpenBeagle server:
-.. code-block:: bash
+.. code-block:: shell
git push origin demo-branch
@@ -292,88 +305,86 @@ Merging upstream changes
*************************
We recommend that you don't actually make any changes to the **main**
-branch in your local repository (or your fork onGitLab). Instead, use
+branch in your local repository (or your fork on OpenBeagle). Instead, use
named branches to do any of your own work. The advantage of this
approach it is the trivial to pull the upstream **main** (i.e. the
official BeagleBoard branch) to your repository.
Assuming you have issued this command (you only need to do this once):
-.. code-block:: bash
+.. code-block:: shell
- git remote add upstream https://openbeagle.org/docs/docs.beagleboard.io/
+ git remote add upstream https://openbeagle.org/docs/docs.beagleboard.io
Then all you need to do is:
-.. code-block:: bash
+.. code-block:: shell
- git checkout main pull upstream main
+ git checkout main
+ git pull upstream main
Provided you never commit any change to your local **main** branch,
this should always be a simple *fast forward* merge without any
conflicts. You can then deal with merging the upstream changes from your
local main branch into your local branches (and you can do that offline).
-If you have your repository hosted online (e.g. at GitLab), then push
+If you have your repository hosted online (e.g. at OpenBeagle), then push
the updated main branch there:
-.. code-block:: bash
+.. code-block:: shell
git push origin main
-Submitting changes for inclusion in BeagleBoard
-*************************************************
+Submitting changes for inclusion in BeagleBoard Docs
+*****************************************************
-If you think you changes are worth including in the main BeagleBoard
-distribution, then file an (enhancement) bug on our bug
+If you think you changes are worth including in the main BeagleBoard Docs
+distribution, then file a report on our issue
tracker, and include a link to your updated branch (i.e. your branch on
-GitLab, or another public Git server). You could also attach a patch to the bug.
-If the changes are accepted, one of the BeagleBoard developers will have to check
+OpenBeagle, or another public ``git`` server). You could also attach a patch to the bug.
+If the changes are accepted, one of the BeagleBoard Docs developers will have to check
this code into our main repository.
-On GitLab itself, you can inform keepers of the main branch of your
-changes by sending a 'pull request' from the main page of your branch.
-Once the file has been committed to the main branch, you may want to
-delete your now redundant bug fix branch on GitLab.
+On OpenBeagle itself, you can inform keepers of the main branch of your
+changes by sending a 'merge request' from the page of your branch.
If other things have happened since you began your work, it may require
merging when applied to the official repository's main branch. In this
-case we might ask you to help by rebasing your work:
+case, we might ask you to help by rebasing your work:
-.. code-block:: bash
+.. code-block:: shell
- git fetch upstream checkout demo-branch
-
-.. code-block:: bash
-
+ git fetch upstream
+ git checkout demo-branch
git rebase upstream/main
-Hopefully the only changes between your branch and the official repository's
-main branch are trivial and git will handle everything automatically.
+Hopefully, the only changes between your branch and the official repository's
+main branch are trivial and ``git`` will handle everything automatically.
If not, you would have to deal with the clashes manually. If this works,
-you can update the pull request by replacing the existing (pre-rebase) branch:
+you can update the merge request by replacing the existing (pre-rebase)
+branch:
-.. code-block:: bash
+.. code-block:: shell
- git push origin demo-branch --force
+ git push origin demo-branch
If however the rebase does not go smoothly, give up with the following command
-(and hopefully the BeagleBoard developers can sort out the rebase or merge for you):
+(and hopefully the BeagleBoard Docs developers can sort out the rebase or merge for you):
-.. code-block:: bash
+.. code-block:: shell
git rebase --abort
Evaluating changes
-********************
+******************
-Since git is a fully distributed version control system, anyone can
+Since ``git`` is a fully distributed version control system, anyone can
integrate changes from other people, assuming that they are using
branches derived from a common root. This is especially useful for
people working on new features who want to accept contributions from
other people.
-This section is going to be of particular interest for the BeagleBoard
+This section is going to be of particular interest for the BeagleBoard Docs
core developers, or anyone accepting changes on a branch.
For example, suppose Jason has some interesting changes on his public
@@ -381,23 +392,23 @@ repository:
https://openbeagle.org/jkridner/docs.beagleboard.io
-You must tell git about this by creating a reference to this remote
+You must tell ``git`` about this by creating a reference to this remote
repository:
-.. code-block:: bash
+.. code-block:: shell
- git remote add jkridner https://openbeagle.org/jkridner/BeagleBoard.git
+ git remote add jkridner https://openbeagle.org/jkridner/docs.beagleboard.io
Now we can fetch *all* of Jason's public repository with one line:
-.. code-block:: bash
+.. code-block:: shell
git fetch jkridner
Now we can run a diff between any of our own branches and any of Jason's
branches. You can list your own branches with:
-.. code-block:: bash
+.. code-block:: shell
git branch
@@ -405,14 +416,14 @@ Remember the asterisk shows which branch is currently checked out.
To list the remote branches you have setup:
-.. code-block:: bash
+.. code-block:: shell
git branch -r
For example, to show the difference between your **main** branch and
Jason's **main** branch:
-.. code-block:: bash
+.. code-block:: shell
git diff main jkridner/main
@@ -420,7 +431,7 @@ If you are both keeping your **main** branch in sync with the upstream
BeagleBoard repository, then his **main** branch won't be very
interesting. Instead, try:
-.. code-block:: bash
+.. code-block:: shell
git diff main jkridner/awesomebranch
@@ -428,16 +439,16 @@ You might now want to merge in (some) of Jason's changes to a new branch
on your local repository. To make a copy of the branch (e.g. awesomebranch)
in your local repository, type:
-.. code-block:: bash
+.. code-block:: shell
git checkout --track jkridner/awesomebranch
If Jason is adding more commits to his remote branch and you want to update
your local copy, just do:
-.. code-block:: bash
+.. code-block:: shell
- git checkout awesomebranch # if you are not already in branch awesomebranch pull
+ git checkout awesomebranch # if you are not already in branch awesomebranch
If you later want to remove the reference to this particular branch:
@@ -451,128 +462,21 @@ Or, to delete the references to all of Jason's branches:
.. code-block:: console
$ git remote rm jkridner
-
$ git branch -r
upstream/main
origin/HEAD
origin/main
-Alternatively, from within GitLab you can use the fork-queue to cherry
+Alternatively, from within OpenBeagle you can use the fork-queue to cherry
pick commits from other people's forked branches. While this
defaults to applying the changes to your current branch, you would
typically do this using a new integration branch, then fetch it to your
-local machine to test everything, before merging it to your main branch.
-
-Committing changes to main branch
-**********************************
-
-This section is intended for BeagleBoard developers, who are allowed to
-commit changes to the BeagleBoard main "official" branch. It describes the
-typical activities, such as merging contributed code changes both from
-git branches and patch files.
-
-Prerequisites
-==============
-
-Currently, the main BeagleBoard branch is hosted on OpenBeagle. In order to
-make changes to the main branch you need a OpenBeagle account and you need
-to be added as a collaborator/Maintainer to the BeagleBoard account.
-This needs to be done only once. If you have a OpenBeagle account, but you are not yet a
-collaborator/Maintainer and you think you should be ask Jason to be added (this is meant for
-regular contributors, so in case you have only a single change to make,
-please consider submitting your changes through one of developers).
-
-Once you are a collaborator/Maintainer, you can pull BeagleBoard official branch
-using the private url. If you want to make a new repository (linked to
-the main branch), you can just clone it:
-
-.. code-block:: bash
-
- git clone https://openbeagle.org/lorforlinux/docs.beagleboard.io.git
-
-It creates a new directory "docs.beagleboard.io" with a local copy of the official
-branch. It also sets the "origin" to the GitLab copy This is the
-recommended way (at least for the beginning) as it minimizes the risk of
-accidentally pushing changes to the official GitLab branch.
-
-Alternatively, if you already have a working git repo (containing your
-branch and your own changes), you can add a link to the official branch
-with the git "remote command"... but we'll not cover that here.
-
-In the following sections, we assume you have followed the recommended
-scenario and you have the following entries in your .git/config file:
-
-.. code-block:: text
-
- [remote "origin"]
- url = https://openbeagle.org/lorforlinux/docs.beagleboard.io.git
-
- [branch "main"]
- remote = origin
-
-Committing a patch
-===================
-
-If you are committing from a patch, it's also quite easy. First make
-sure you are up to date with official branch:
-
-.. code-block:: bash
-
- git checkout main pull origin
-
-Then do your changes, i.e. apply the patch:
-
-.. code-block:: bash
-
- patch -r someones_cool_feature.diff
-
-If you see that there were some files added to the tree, please add them
-to git:
-
-.. code-block:: bash
-
- git add beaglebone-black/some_new_file
-
-Then make a commit (after adding files):
-
-.. code-block:: bash
-
- git commit -a -m "committed a patch from a kind contributor adding feature X"
-
-After your changes are committed, you can push toGitLab:
-
-.. code-block:: bash
-
- git push origin
-
-Tagging the official branch
-============================
-
-If you want to put tag on the current BeagleBoard official branch (this is
-usually done to mark a new release), you need to follow these steps:
-
-First make sure you are up to date with official branch:
-
-.. code-block:: bash
-
- git checkout main pull origin
-
-Then add the actual tag:
-
-.. code-block:: bash
-
- git tag new_release
-
-And push it to GitLab:
-
-.. code-block:: bash
-
- git push --tags origin main
+local machine to test everything, before merging it to your public working branch.
Additional Resources
-**********************
+********************
-There are a lot of different nice guides to using Git on the web:
+There are a lot of different nice guides to using ``git`` on the web:
- `Understanding Git
Conceptually <https://www.sbf5.com/~cduan/technical/git/>`_
diff --git a/intro/contribution/gsoc.rst b/intro/contribution/gsoc.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7c91d86c604d81cef232d26f2283a6af10d0137a
--- /dev/null
+++ b/intro/contribution/gsoc.rst
@@ -0,0 +1,13 @@
+.. _beagleboard-gsoc:
+
+Google Summer of Code (GSoC)
+############################
+
+GSoC offers a unique opportunity to immerse yourself in open-source development, work closely with mentors, and make significant contributions to coding projects. Beyond the summer, many participants find themselves forging lifelong connections with the open-source community.
+
+BeagleBoard.org actively participates in the Google Summer of Code program as a mentorship organization. This page serves as a hub for mentors and mentees interested in participating in GSoC with BeagleBoard.
+
+Google Summer of Code is open to individuals age 18 and older in most countries who are new or beginner contributors to open source coding projects.
+Read more background on the `GSoC site rules <https://summerofcode.withgoogle.com/rules>`_ page and the `FAQ <https://developers.google.com/open-source/gsoc/faq>`_.
+
+**Get started with BeagleBoard.org at:** `gsoc.beagleboard.io <https://gsoc.beagleboard.io>`_.
diff --git a/intro/contribution/how.rst b/intro/contribution/how.rst
new file mode 100644
index 0000000000000000000000000000000000000000..66ada15ab2c3eb50320b25376297f9233bd001b0
--- /dev/null
+++ b/intro/contribution/how.rst
@@ -0,0 +1,75 @@
+.. _contribution-how:
+
+How can I contribute?
+#####################
+
+The most obvious way to contribute is using the `OpenBeagle (BeagleBoard.org GitLab server) <https://openbeagle.org>`_ to report
+bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
+designs and documentation.
+
+Reading the `help guide <https://openbeagle.org/help/>`_ is a great way to get started using OpenBeagle.
+
+.. _contribution-todo-list:
+
+Tackle to-do list
+*****************
+
+This documentation has a number of ``todo`` items where help is needed that can be searched in the source. This list will
+show up directly in the staging documentation at https://docs.beagleboard.io/latest/intro/contribution/how.html#contribution-todo-list
+
+.. todolist::
+
+Google Summer of Code (GSoC)
+****************************
+
+For newcomers venturing into the realm of open-source contribution, Google Summer of Code (GSoC) stands as an invaluable platform. GSoC provides a unique opportunity to collaborate with the open-source community, engaging in the identification and development of exciting projects during the summer term.
+
+BeagleBoard.org serves as a mentorship organization that takes part in the Google Summer of Code program actively, giving students the opportunity to work on open-source projects during the summer. Visit our dedicated :ref:`beagleboard-gsoc` for more information about this program, including past projects and mentorship opportunities.
+
+Reporting bugs
+***************
+
+Start by reading the `OpenBeagle Issues help page <https://openbeagle.org/help/user/project/issues/index.md>`_.
+
+Please request an account and report any issues on the appropriate project issue tracker at https://openbeagle.org.
+
+Report issues on the software images at https://openbeagle.org/explore/topics/distros.
+
+Report issues on the hardware at https://openbeagle.org/explore/projects/topics/boards.
+
+Suggesting enhancements
+***********************
+
+An issue doesn't have to be something wrong, it can just be about making something better. If in doubt how to make
+a productive suggestion, hop on the forum and live chat groups to see what other people say. Check the current
+ideas that are already out there and give us your idea. Try to be constructive in your suggestion. We are a primarily
+a volunteer community looking to make your experience better, as those that follow you, and your suggestion could be
+key in that endeavor.
+
+Where available, use the "enhancement" `label <https://openbeagle.org/help/user/project/labels.md>`_ on your issue
+to make sure we know you are looking for a future improvement, not reporting something critically wrong.
+
+Submitting merge requests
+*************************
+
+If you want to contribute to a project, the most practical way is with a
+`merge request <https://openbeagle.org/help/user/project/merge_requests/index.html>`_. Start
+by `creating a fork <https://openbeagle.org/help/user/project/repository/forking_workflow.html>`_, which
+is your own copy of the project you can feel free to edit how you see fit. When ready,
+`create a merge request <https://openbeagle.org/help/user/project/merge_requests/creating_merge_requests.html>`_ and
+we'll review your work and give comments back to you. If suitable, we'll update the code to include your contribution!
+
+A bit more detailed suggestions can be found in the articles linked below.
+
+Articles on contribution
+**************************
+
+- :ref:`beagleboard-git-usage`
+- :ref:`beagleboard-doc-style`
+- :ref:`rst-cheat-sheet`
+- :ref:`beagleboard-linux-upstream`
+
+History of contributors
+***********************
+
+- :ref:`contributors`
diff --git a/intro/contribution/index.rst b/intro/contribution/index.rst
index 5a13e23a0a4c942a183e787f9df3c62b1c000141..ba0f71642ae08ec90c626f8b80066c1f006809bb 100644
--- a/intro/contribution/index.rst
+++ b/intro/contribution/index.rst
@@ -3,9 +3,6 @@
Contribution
###############
-.. note::
- This section is under developmement right now.
-
.. important::
First off, thanks for taking the time to think about contributing!
@@ -21,95 +18,16 @@ Example projects suitable for first contributions:
* `Debian image builder <https://openbeagle.org/beagleboard/image-builder>`__
These guidelines are mostly suggestions, not hard-set rules. Use your best judgment, and feel free
-to propose changes to this document in a pull request.
-
-Code of Conduct
-***************
-
-This project and everyone participating are governed by the same code of conduct.
-
-.. note::
- Check out https://forum.beagleboard.org/faq as a starting place for our code of conduct.
-
-By participating, you are expected to
-uphold this code. Please report unacceptable behavior to
-contact one of our administrators or moderators on https://forum.beagleboard.org/about.
-
-Frequently Asked Questions
-**************************
-
-Please refer to the technical and contribution frequently asked questions pages before posting any of your own questions. Please
-feel encouraged to ask follow-up questions if any of the answers are not clear enough.
-
-* `Frequently asked questions contribution category on the BeagleBoard.org Forum <https://forum.beagleboard.org/c/faq>`__
-
-What should I know before I get started?
-****************************************
-
-The more you know about Linux and contributing to upstream projects, the better, but this knowledge isn't strictly required. Simply
-reading about contributing to Linux and upstream projects can help build your vocabulary in a meaningful way to help out. Learn about
-the skills required for Linux contributions in the :ref:`beagleboard-linux-upstream` section.
-
-The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask
-smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation.
-
-How can I contribute?
-*********************
-
-The most obvious way to contribute is using the `OpenBeagle <https://openbeagle.org/>`_ (BeagleBoard.org GitLab server) to report
-bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
-designs and documentation.
-
-Reading the `help guide <https://openbeagle.org/help/>`_ is a great way to get started using our Gitlab server.
-
-.. note::
- This documentation has a number of ``todo`` items where help is needed that can be searched in the
- `source <https://openbeagle.org/docs/docs.beagleboard.io>`_. This list will
- show up directly in the `staging documentation <https://docs.beagleboard.io/latest/intro/contribution/index.html#how-can-i-contribute>`_.
-
-.. todolist::
-
-Reporting bugs
-===============
-
-Start by reading the `Gitlab Issues help page <https://openbeagle.org/help/user/project/issues/index.md>`_.
-
-Please request an account and report any issues on the appropriate project issue tracker at https://openbeagle.org/.
-
-Report issues on the software images at https://beagleboard.org/explore/topics/distros.
-
-Report issues on the hardware at https://beagleboard.org/explore/projects/topics/boards.
-
-Suggesting enhancements
-=======================
-
-An issue doesn't have to be something wrong, it can just be about making something better. If in doubt how to make
-a productive suggestion, hop on the forum and live chat groups to see what other people say. Check the current
-ideas that are already out there and give us your idea. Try to be constructive in your suggestion. We are a primarily
-a volunteer community looking to make your experience better, as those that follow you, and your suggestion could be
-key in that endeavor.
-
-Where available, use the "enhancement" `label <https://openbeagle.org/help/user/project/labels.md>`_ on your issue
-to make sure we know you are looking for a future improvement, not reporting something critically wrong.
-
-Submitting merge requests
-=========================
-
-If you want to contribute to a project, the most practical way is with a
-`merge request <https://openbeagle.org/help/user/project/merge_requests/index.html>`_. Start
-by `creating a fork <https://openbeagle.org/help/user/project/repository/forking_workflow.html>`_, which
-is your own copy of the project you can feel free to edit how you see fit. When ready,
-`create a merge request <https://openbeagle.org/help/user/project/merge_requests/creating_merge_requests.html>`_ and
-we'll review your work and give comments back to you. If suitable, we'll update the code to include your contribution!
-
-A bit more detailed suggestions can be found in the articles linked below.
-
-Articles on contribution
-**************************
+to propose changes to this document in a merge request.
.. toctree::
- :maxdepth: 1
-
+ :maxdepth: 2
+
+ code-of-conduct
+ faq
+ background
+ how
+ gsoc
git-usage
style
rst-cheat-sheet
diff --git a/intro/contribution/rst-cheat-sheet.rst b/intro/contribution/rst-cheat-sheet.rst
index 45b9361b1c9592290d5e2f770dd72595a6e68fcb..f02cb7a75d0984d8e5b7a8f30c4c1b287d487b01 100644
--- a/intro/contribution/rst-cheat-sheet.rst
+++ b/intro/contribution/rst-cheat-sheet.rst
@@ -325,40 +325,36 @@ Then the reference will be rendered as: :ref:`rst-cheat-sheet`.
YouTube Videos
==============
-This section shows you the typical way of adding a YouTube video to
-docs.BeagleBoard.org in a way that you see on page playable embedded
-YouTube video when you look at HTML version of the docs and only a
-clicable thumnail linked to the YouTube video when you see the PDF.
+This site uses sphinxcontrib-youtube to embed YouTube videos. The syntax is as follows:
.. callout::
.. code-block:: rst
- .. only:: latex
-
- .. image:: https://img.youtube.com/vi/<YouTube_video_ID>/maxresdefault.jpg <1>
- :alt: BeagleConnect unboxing YouTube video
- :width: 1280
- :target: https://www.youtube.com/watch?v=<YouTube_video_ID> <2>
+ .. _internal-link: <1>
- .. only:: html
+ .. admonition:: YouTube Video Description <2>
- .. raw:: html
-
- <iframe style="display: block; margin: auto;" width="1280" height="720" style="align:center"
- src="https://www.youtube.com/embed/<YouTube_video_ID>" <3>
- title="YouTube video player"
- frameborder="0"
- allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
- allowfullscreen>
- </iframe>
+ .. youtube:: <YouTube_video_ID> <3>
.. annotations::
- <1> <2> <3> Here you have to replace the <YouTube_video_ID> with your actual youtube ID.
+ <1> Internal link to the video to be used for references.
+
+ <2> Title for your video.
+
+ <3> Here you have to replace the <YouTube_video_ID> with your actual YouTube ID.
+
+When rendered, it looks like :ref:`youtube-example`.
+
+.. _youtube-example:
+
+.. admonition:: Example of embedded YouTube video
+
+ .. youtube:: 7cm1AAnaawk
More
-====
+****
.. rubric:: footnotes
diff --git a/intro/support/getting-started.rst b/intro/support/getting-started.rst
index 37bf7272da857c4c04aac098dbda9f2c5b535d99..1ec6258c418e499f152827750e7d83ccfa76404f 100644
--- a/intro/support/getting-started.rst
+++ b/intro/support/getting-started.rst
@@ -136,6 +136,8 @@ to your computer. If your computer supports mDNS, you should see your Beagle as
Non-BeagleBone boards will utilize alternate names. Multiple BeagleBone boards on the same
network will add a suffix such as beaglebone-2.local.
+.. _start-browse-to-beagle:
+
Browse to your Beagle
============================
diff --git a/requirements.txt b/requirements.txt
index 9e3e5d93fdab5149b429949a456f249c9fef5008..83a0822458c0c653f29bc55a54b494994b17634f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -33,5 +33,6 @@ sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-serializinghtml==1.1.9
sphinxcontrib-svg2pdfconverter==1.2.2
+sphinxcontrib-youtube==1.4.1
tornado==6.4
urllib3==2.1.0
diff --git a/venv-build-env.sh b/venv-build-env.sh
index 5993ce8fe0f73655fd882f6bd5a612b3c5867767..ea57e6d5037f20a52bb59912ed38025a03c2b6e3 100755
--- a/venv-build-env.sh
+++ b/venv-build-env.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/sh -ex
# Source this script like `. ./venv-build-env.sh`
if [ ! -e ./.venv ]; then
python3 -m venv .venv