Unify Beluga documentation

.clang-format

@@ -4,4 +4,7 @@ Language: Cpp
 PointerAlignment: Left
 ColumnLimit: 120
 AlignAfterOpenBracket: AlwaysBreak
+---
+BasedOnStyle: Chromium
+Language: JavaScript
 ...

.github/workflows/ci_pipeline.yml

@@ -89,13 +89,9 @@ jobs:
         working-directory: ${{ github.workspace }}
         run: ./src/beluga/tools/build-and-test.sh
 
-      - name: Upload documentation artifacts
-        uses: actions/upload-artifact@v3
-        with:
-          name: docs
-          path: ./build/beluga/docs/html/
-          retention-days: 7
-        if: ${{ matrix.upload_artifacts }}
+      - name: Perform static analysis
+        working-directory: ${{ github.workspace }}
+        run: ./src/beluga/tools/run-clang-tidy.sh
 
       - name: Upload code coverage report
         uses: codecov/codecov-action@v3
@@ -107,14 +103,35 @@ jobs:
           verbose: true
         if: ${{ matrix.upload_artifacts }}
 
-      - name: Static analysis
-        working-directory: ${{ github.workspace }}
-        run: ./src/beluga/tools/run-clang-tidy.sh
+  build-docs:
+    needs: build-test
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          cache: pip
+
+      - name: Install tooling dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: make -C docs html
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: ./docs/_build/html/
+          retention-days: 7
 
   deploy-docs:
-    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-    needs: build-test
+    needs: build-docs
     runs-on: ubuntu-22.04
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     steps:
       - name: Checkout documentation branch
         uses: actions/checkout@v3

.gitignore

@@ -4,10 +4,14 @@ install/
 lcov/
 logs/
 
-
 # Python related
 __pycache__/
+**/venv/
 
 # Development environments
 .vscode/
 .idea/
+
+# Sphinx / Doxygen related
+_build
+generated

.pre-commit-config.yaml

@@ -21,6 +21,7 @@ repos:
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
       - id: check-yaml
+        args: [--allow-multiple-documents]
       - id: check-xml
       - id: end-of-file-fixer
       - id: trailing-whitespace

CONTRIBUTING.md

@@ -107,18 +107,22 @@ This projects adopts a [feature branch workflow](https://about.gitlab.com/topics
 
 #### How Do I Submit a Good Code Contribution?
 
-1. **Fork [the Beluga repository](https://github.com/Ekumen-OS/beluga/) to your GitHub account**.
-1. **Clone the repository fork locally**.
+1. **Fork the [Beluga repository](https://github.com/Ekumen-OS/beluga/) to your GitHub account**.
+1. **Clone the repository fork locally**. You will need `git`.
    ```bash
    git clone --recursive [email protected]:<your_username>/beluga.git
+   ```
+1. **Install pre-commit hooks**. You will need [`pre-commit`](https://pre-commit.com).
+   ```bash
    cd beluga
+   pre-commit install
    ```
 1. **Create a new branch where your work will go**.
    ```bash
    git checkout -b <your_username>/fix-issue-12345 main
    ```
 1. **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development.
-1. **Lint and test your changes**. For bug fixes, make sure regression tests are included.
+1. **Test your changes**. For bug fixes, make sure regression tests are included.
 1. **Document your changes as needed**. For new features, make sure added functionality is clearly documented.
 1. **Push the branch to your fork on GitHub**.
 1. **Open a pull request**. Make sure all tests and linters pass on your branch before opening.

DEVELOPING.md

@@ -0,0 +1,76 @@
+# Developing Beluga
+
+## Table of Contents
+
+- [Environment](#environment)
+- [Workflow](#workflow)
+- [CI/CD](#ci-cd)
+
+## Environment
+
+Beluga developers use [Docker](https://www.docker.com) containers as development environment. These containers include both project dependencies and development tooling for each of the supported platforms. Source code [bind mounts](https://docs.docker.com/storage/bind-mounts) afford Beluga developers the freedom of applying their own personal programming workflows to Beluga (e.g. which editor to use), so long as they are compatible with the project guidelines.
+
+To bring up a development environment:
+
+1. **Clone the repository**. You will need `git`.
+
+   ```bash
+   git clone --recursive [email protected]:Ekumen-OS/beluga.git
+   ```
+
+2. **Build and run the development container**. You will need [`docker-compose v2.10+`](https://github.com/docker/compose/tree/v2).
+
+   ```bash
+   (cd beluga && docker/run.sh)
+   ```
+
+   To rebuild the image before starting the container, use:
+
+   ```bash
+   (cd beluga && docker/run.sh --build)
+   ```
+
+   To target an specific ROS distribution, use:
+
+   ```bash
+   (cd beluga && ROSDISTRO=humble docker/run.sh)
+   ```
+
+   Supported distributions include `noetic`, `humble`, `iron`, and `rolling`.
+
+## Workflow
+
+The Beluga project started as a ROS 2 project and therefore relies on a typical ROS 2 workflow. In particular, the Beluga project subscribes to [REP-2004](https://ros.org/reps/rep-2004.html) and aims for Quality Level 1. For development, this translates to mandatory API documentation and a 95% code coverage policy for unit and integration testing.
+
+Within a development environment:
+
+1. **Build and test the project**. You will usually use `colcon`.
+
+    ```bash
+    cd /ws
+    colcon build --symlink-install
+    colcon test
+    ```
+
+    You may also use `catkin_make_isolated` and `catkin-tools` for ROS 1 distributions.
+
+2. **Update package dependencies**. Listed in `package.xml` files.
+
+    ```bash
+    cd /ws
+    rosdep update
+    rosdep install --from-path src
+    ```
+
+For more advanced tooling, check repository [tools](./tools).
+
+## CI/CD
+
+Every pull request and every push to the project repository `main` branch will be subject to a [continuous integration workflow](./.github/workflows/ci_pipeline.yml). This workflow will lint project sources, static analyze, build, and test project packages against the project platform support matrix, enforcing its code coverage policy, and build project documentation (which will be deployed to Github Pages when pushing to `main`).
+
+Pull request acceptance is predicated on these checks passing.
+
+## Next Steps
+
+- Go over the [project documentation](https://ekumen-os.github.io/beluga) to better understand what, how, and why.
+- If you want to contribute to this project, please read the [contribuing guidelines](CONTRIBUTING.md) first.

README.md

@@ -42,7 +42,5 @@ This repository contains the following packages:
 
 ## ⚙️ First Steps
 
-- Get hands-on experience with the [getting started](GETTING_STARTED.md) tutorial.
-- Check the [installation guide](INSTALLING.md) to test this on a robot.
-- Check the [API documentation](https://ekumen-os.github.io/beluga/) for information on how to use the library in your project.
+- Go check the [project documentation](https://ekumen-os.github.io/beluga).
 - Read the [contributing guidelines](CONTRIBUTING.md).

beluga/CMakeLists.txt

@@ -75,12 +75,6 @@ if(BUILD_TESTING)
   add_subdirectory(test)
 endif()
 
-option(BUILD_DOCS "Build API documentation." OFF)
-if(BUILD_DOCS)
-  message(STATUS "Build API documentation enabled.")
-  add_subdirectory(docs)
-endif()
-
 set(INSTALL_CMAKEDIR ${CMAKE_INSTALL_PREFIX}/share/${PROJECT_NAME}/cmake)
 
 install(DIRECTORY include/ DESTINATION include/${PROJECT_NAME})