merge: pull request #109 from insertish/insert/chore/docs-deployment

chore: configuration required for deploying docs

.github/workflows/documentation.yml

@@ -0,0 +1,56 @@
+name: Build & Deploy Documentation
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - name: Checkout repository and submodules
+        uses: actions/checkout@v3
+        with:
+          path: "src/lasr-base"
+
+      - name: Install ROS Noetic
+        run: |
+          sudo add-apt-repository universe
+          sudo add-apt-repository restricted
+          sudo add-apt-repository multiverse
+
+          sudo apt update
+
+          sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
+
+          sudo apt install curl # if you haven't already installed curl
+          curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
+
+          sudo apt update
+          sudo apt install ros-noetic-ros-base python3-catkin-tools
+
+      - name: Build documentation package
+        run: |
+          source /opt/ros/noetic/setup.bash
+          catkin build documentation
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: Build documentation
+        run: |
+          source /opt/ros/noetic/setup.bash
+          source devel/setup.bash
+          rosrun documentation build.py
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.event_name != 'pull_request' && github.ref_name == 'main'
+        with:
+          deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }}
+          publish_dir: ./src/lasr-base/documentation/web/build
+          external_repository: lasr-at-home/docs

documentation/CMakeLists.txt

@@ -158,6 +158,7 @@ include_directories(
 catkin_install_python(PROGRAMS
   scripts/dev.py
   scripts/view.py
+  scripts/build.py
   scripts/generate_readme.py
   scripts/generate_all_lasr.py
   DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}

documentation/scripts/build.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+import document_lasr
+import subprocess
+
+document_lasr.configure_web()
+subprocess.call("npm i", shell=True)
+subprocess.call("npm run build", shell=True)

documentation/web/docs/guides/container.md

@@ -10,14 +10,14 @@ To build the container, ensure you have a copy of the TIAGo Melodic container an
 git clone https://github.com/lasr-at-home/containers.git ~/containers
 cd ~/containers
 
-# copy base container to tiago_pal_melodic.sif to current directory
+# copy TIAGo container to tiago_noetic_opensource.sif to current directory
 
 sudo apptainer build robocup_container.sif robocup_container.def
 ```
 
-:::note
+:::danger
 
-This also works with the open source container.
+This likely doesn't work with the proprietary PAL container for the time being.
 
 :::
 
@@ -29,78 +29,66 @@ You can save a lot of time debugging build errors by redirecting all output to a
 rm build.log 2>/dev/null; sudo apptainer build robocup_container.sif robocup_container.def 2>&1 | tee build.log
 ```
 
+### Checking when container was built
+
+You can quickly check what container you're using by running the following:
+
+```bash
+$ cat /.build_info
+RoboCup Container (Version: 0001, Bootstrapped from: oss, Build date: 09-11-2023, Build took: 0 days 0 hours 8 minutes 36 seconds)
+```
+
 ### Testing new dependencies
 
-If you'd like to test new dependencies without rebuilding the entire container, you can use the `stage2` definition file.
+If you'd like to test new dependencies without rebuilding the entire container, you can use the `test_container_template` definition file.
 
 After building the RoboCup container, you can then run:
 
 ```bash
-sudo apptainer build stage2.sif stage2.def
+sudo apptainer build test_container_template.sif test_container_template.def
 
 # .. with log:
-rm build.log 2>/dev/null; sudo apptainer build stage2.sif stage2.def 2>&1 | tee build.log
+rm build.log 2>/dev/null; sudo apptainer build test_container_template.sif test_container_template.def 2>&1 | tee build.log
 ```
 
 ## Container
 
 This section goes over how the container is built.
 
-We use the TIAGo Melodic container as a base which uses Ubuntu 18.04 as a base itself.
+We use the TIAGo Noetic container as a base which uses Ubuntu 21.04 as a base itself.
 
 ### Install packages from repositories
 
 1. Ensure the container is up to date by updating and upgrading from PAL apt repositories.
 
 2. Install additional apt packages
 
-   | Package | Description |
-   |:-:|---|
-   | ros-melodic-audio-common | provides various ROS packages for capturing and playing back audio |
-   | python3-numpy | numpy package for Python 3.6 |
-   | python3-opencv | cv2 package for Python 3.6 |
-   | libasound-dev<br/>libportaudio2<br/>libportaudiocpp0<br/>portaudio19-dev | libraries required to build PyAudio wheel |
-   | ffmpeg | record, convert, and stream audio / video |
+   |                                 Package                                  | Description                                                        |
+   | :----------------------------------------------------------------------: | ------------------------------------------------------------------ |
+   |                         ros-melodic-audio-common                         | provides various ROS packages for capturing and playing back audio |
+   |                              python3-numpy                               | numpy package for Python 3.6                                       |
+   |                              python3-opencv                              | cv2 package for Python 3.6                                         |
+   | libasound-dev<br/>libportaudio2<br/>libportaudiocpp0<br/>portaudio19-dev | libraries required to build PyAudio wheel                          |
+   |                                  ffmpeg                                  | record, convert, and stream audio / video                          |
+   |                  python3-testresources<br/>python3-empy                  | dependencies for catkin_virtualenv                                 |
+   |                    ca-certificates<br/>curl<br/>gnupg                    | generic requirements required by most things                       |
+   |                                    bc                                    | arithmetic for the terminal, used in container build script        |
 
-   :::caution
+:::caution
 
-   Software packages on PAL repositories are quite old, there are situations where it is advisable to install software through alternative means.
+Software packages on PAL repositories are quite old, there are situations where it is advisable to install software through alternative means.
 
-   :::
+:::
 
-3. Install Node.js 16
+3. Install Node.js 20 (LTS as of 09-11-2023)
 
    All available distributions are [listed here](https://github.com/nodesource/distributions).
 
-   :::caution
-
-   Node.js 16 is the latest that may be installed for Ubuntu 18.04. Their build system is currently broken for Node.js 18 and later. When upgrading to noetic, Node.js should be pinned to LTS.
-
-   :::
-
-4. Install additional Python 3.6 packages
-
-   | Package | Version | Description |
-   |:-:|:-:|---|
-   | rosnumpy | 0.0.5.2 | conversion helper between ROS and numpy † |
-   | scipy | 1.5.4 | mathematics library |
-   | black | 22.8.0 | Python code formatter |
-   | scikit-build | 0.16.7 | build system for CPython C/C++/Fortran/Cython extensions using CMake |
-   | scikit-learn | 0.24.2 | machine learning and data mining |
-   | nvidia-ml-py3 | 7.352.0 | bindings for NVIDIA Management Library |
-   | torch | 1.9.1+cpu | neural networks |
-   | torchvision | 0.10.1+cpu | torch extension for vision |
-   | torchaudio | 0.9.1 | torch extension for audio |
-
-   † This library does not work on Python 3.10, ROS packages upgrading to newer Python versions must find a substitute.
-
-   ‡ Installed with CPU support only, [see this page for more information](https://pytorch.org/get-started/previous-versions/#linux-and-windows-17).
-
-5. Create a temporary `/deps` folder which will be used to build additional dependencies in.
+4. Create a temporary `/deps` folder which will be used to build additional dependencies in.
 
-### Install Python 3.10 from source
+### Install Python from source
 
-We install Python 3.10 to take advantage of modern Python libraries which no longer support Python 3.6, we can selectively choose to use it for some of our packages through the use of [catkin virtualenv](/guides/virtualenv). This build step is derived from the [Python documentation](https://devguide.python.org/getting-started/setup-building/).
+We install Python 3.9 and 3.10 to take advantage of modern Python libraries which no longer support Python 3.8, we can selectively choose to use it for some of our packages through the use of [catkin virtualenv](/guides/virtualenv). This build step is derived from the [Python documentation](https://devguide.python.org/getting-started/setup-building/).
 
 1. Install dependencies required for build.
 
@@ -118,13 +106,13 @@ We install Python 3.10 to take advantage of modern Python libraries which no lon
 
 4. Install additional global packages.
 
-   | Package | Version | Description |
-   |:-:|:-:|---|
-   | pyyaml | 6.0.1 | provides yaml package (required by rospy) |
-   | rospkg | 1.5.0 | environment agnostic ROS package utilities (required by rospy) |
-   | pip | 23.2.1 | Python package manager |
-   | setuptools | 68.0.0 | Python build tools |
-   | wheel | 0.41.1 | Python build tools |
+   |  Package   | Version | Description                                                    |
+   | :--------: | :-----: | -------------------------------------------------------------- |
+   |   pyyaml   |  6.0.1  | provides yaml package (required by rospy)                      |
+   |   rospkg   |  1.5.0  | environment agnostic ROS package utilities (required by rospy) |
+   |    pip     | 23.2.1  | Python package manager                                         |
+   | setuptools | 68.0.0  | Python build tools                                             |
+   |   wheel    | 0.41.1  | Python build tools                                             |
 
 :::note
 
@@ -138,6 +126,8 @@ apt install software-properties-common -y && apt-add-repository ppa:deadsnakes/p
 && apt update && apt install python3.8 python3.8-dev python3-setuptools [.. etc]
 ```
 
+NB. update our definition to use this if Ubuntu 21.04 is still supported.
+
 :::
 
 :::warning
@@ -150,26 +140,43 @@ Python 3.11+ is incompatible with rospy (Melodic & Noetic)
 
 1. Reconfigure Python symlinks
 
-   - `/usr/bin/python` is made to point to Python 2.7
-   - `/usr/local/bin/python3` is removed to restore Python 3.6 for `python3`
+   - `/usr/bin/python` is made to point to Python 3.8
+   - `/usr/local/bin/python3` is removed to restore Python 3.8 for `python3`
+
+2. ~~Install additional Python 3.6 packages~~
+
+   :::caution
 
-2. Force catkin build tool to use Python 3.10
+   As Python 3.6 is no longer available in the base container, this has been momentarily removed.
 
-   This step is necessary to get `catkin_virtualenv` to work properly.
+   :::
 
-   We create a folder `/path/python3.10` which contains a single symlink for `python3` which we can then prepend to the PATH when invoking catkin.
+   |    Package    |  Version   | Description                                                          |
+   | :-----------: | :--------: | -------------------------------------------------------------------- |
+   |   rosnumpy    |  0.0.5.2   | conversion helper between ROS and numpy †                            |
+   |     scipy     |   1.5.4    | mathematics library                                                  |
+   |     black     |   22.8.0   | Python code formatter                                                |
+   | scikit-build  |   0.16.7   | build system for CPython C/C++/Fortran/Cython extensions using CMake |
+   | scikit-learn  |   0.24.2   | machine learning and data mining                                     |
+   | nvidia-ml-py3 |  7.352.0   | bindings for NVIDIA Management Library                               |
+   |     torch     | 1.9.1+cpu  | neural networks                                                      |
+   |  torchvision  | 0.10.1+cpu | torch extension for vision                                           |
+   |  torchaudio   |   0.9.1    | torch extension for audio                                            |
 
-   We only want to override `catkin build` so this should be sufficient.
+   † This library does not work on Python 3.10, ROS packages upgrading to newer Python versions must find a substitute.
+
+   ‡ Installed with CPU support only, [see this page for more information](https://pytorch.org/get-started/previous-versions/#linux-and-windows-17).
 
 ### Create overlay workspace for additional ROS packages
 
 1. Create a new overlay workspace
 
 2. Clone ROS packages we want to build from source
 
-   | Package | Description | Source |
-   |:-:|---|---|
-   | catkin_virtualenv | Bundle python requirements in a catkin package via virtualenv | [locusrobotics/catkin_virtualenv](https://github.com/locusrobotics/catkin_virtualenv) @ `4af9970` |
+   |       Package       | Description                                                                 | Source                                                                                            |
+   | :-----------------: | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+   |  catkin_virtualenv  | Bundle python requirements in a catkin package via virtualenv               | [locusrobotics/catkin_virtualenv](https://github.com/locusrobotics/catkin_virtualenv) @ `4af9970` |
+   | video_stream_opencv | Package providing various utilities concerning capturing and playing videos | [ros-drivers/video_stream_opencv](https://github.com/ros-drivers/video_stream_opencv) @ `65949bd` |
 
 3. Build the workspace
 
@@ -187,4 +194,11 @@ Python 3.11+ is incompatible with rospy (Melodic & Noetic)
 
 1. Remove the build folder `/deps`
 
-2. Remove extraneous environment variables
+2. Generate build information for future reference
+
+   ```bash
+   $ cat /.build_info
+   RoboCup Container (Version: 0001, Bootstrapped from: oss, Build date: 09-11-2023, Build took: 0 days 0 hours 8 minutes 36 seconds)
+   ```
+
+3. Remove extraneous environment variables

documentation/web/docs/guides/virtualenv.md

@@ -15,8 +15,8 @@ Find the line in the definition file where Python dependencies are declared:
 ```diff
 # Additional Python packages
 + # pyyaml: yaml library
-- python3.6 -m pip install rosnumpy==0.0.5.2 scipy==1.5.4
-+ python3.6 -m pip install rosnumpy==0.0.5.2 scipy==1.5.4 pyyaml==6.0.1
+- python3.8 -m pip install rosnumpy==0.0.5.2 scipy==1.5.4
++ python3.8 -m pip install rosnumpy==0.0.5.2 scipy==1.5.4 pyyaml==6.0.1
 ```
 
 Then update the container maintenance document accordingly, you can do this by going to [Container Maintenance](/guides/container) and then clicking edit page at the bottom.
@@ -25,16 +25,17 @@ Then update the container maintenance document accordingly, you can do this by g
 
 :::caution
 
-Using catkin_virtualenv requires that catkin itself uses Python 3.7 or later during the build process, this is already managed for you by the container however may prove to be an issue if building a new container.
+Using catkin_virtualenv requires that catkin itself uses Python 3.8 or later during the build process, this is already managed for you by the container however may prove to be an issue if building a new container.
 
 :::
 
 :::note
 
 The following Python versions are available in the container:
 
-- Python 2.7
-- Python 3.6
+- Python 2.7 (do not use)
+- Python 3.8 (from TIAGo container)
+- Python 3.9
 - Python 3.10 (recommended)
 
 :::
@@ -159,6 +160,6 @@ If you want to update packages or install new packages, delete the `requirements
 
 :::tip
 
-This also integrates with the `document_lasr` package, you can regenerate your README to include / update your Python dependencies. 
+This also integrates with the `documentation` package, you can regenerate your README to include / update your Python dependencies.
 
 :::

documentation/web/docusaurus.config.js

@@ -10,15 +10,16 @@ const config = {
   tagline: "LASR Web Documentation",
 
   // Set the production url of your site here
-  url: "https://your-docusaurus-test-site.com",
+  url: "https://lasr-at-home.github.io/",
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: "/",
+  baseUrl: "/docs/",
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
-  organizationName: "facebook", // Usually your GitHub org/user name.
-  projectName: "docusaurus", // Usually your repo name.
+  organizationName: "lasr-at-home", // Usually your GitHub org/user name.
+  projectName: "docs", // Usually your repo name.
+  trailingSlash: false,
 
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
@@ -40,7 +41,7 @@ const config = {
           routeBasePath: "/",
           sidebarPath: require.resolve("./sidebars.js"),
           editUrl:
-          'https://github.com/lasr-at-home/base/blob/main/common/document_lasr/web',
+            "https://github.com/lasr-at-home/base/blob/main/common/document_lasr/web",
         },
       }),
     ],