Unify Beluga documentation (#346)

### Proposed changes

This patch unifies all repository documentation in a common Sphinx site:
high-level documentation lives in [MyST](https://mystmd.org/) flavor
Markdown documents, Doxygen API documentation is pulled in using the
`autodox` extension in https://github.com/Ekumen-OS/sphinx-babel.

In the process, this PR partially addresses #301, #302, #303, #304, and
#308.

#### Type of change

- [ ] 🐛 Bugfix (change which fixes an issue)
- [ ] 🚀 Feature (change which adds functionality)
- [x] 📚 Documentation (change which fixes or extends documentation)

💥 **Breaking change!** This patch changes the way we used to build
documentation for the Beluga package.

### Checklist

- [x] Lint and unit tests (if any) pass locally with my changes
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have added necessary documentation (if appropriate)
- [x] All commits have been signed for
[DCO](https://developercertificate.org/)

### Additional comments

This patch gets us 80% of the way towards release ready documentation.
High-level documentation is not as polished as I would like to
(specially the Key Concepts page), but this patch is big enough already
and I'm too drained to produce quality technical writing. The easiest
way to review this is building documentation locally and exploring it.
You can check the README file under `docs` for instructions, or simply:

```
git clone https://github.com/Ekumen-OS/beluga.git
cd beluga/docs
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
make html 
```

Note this documentation needs Python 3.9 or later to build. I was not
able to get all dependencies to play ball in earlier Python versions.

---------

Signed-off-by: Michel Hidalgo <[email protected]>

.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,43 @@ 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: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            doxygen \
+            git \
+            graphviz \
+            make \
+            texlive-latex-base
+          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})