docs: Install pandoc github action

.github/workflows/docs.yml

@@ -1,39 +1,51 @@
-# Copyright DB InfraGO AG and contributors
+# SPDX-FileCopyrightText: Copyright DB InfraGO AG
 # SPDX-License-Identifier: CC0-1.0
 
 name: Docs
 
 on:
-  push:
-    branches: ["master"]
+    workflow_dispatch:
+    push:
+        branches: [master]
 
 jobs:
-  sphinx:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.10"
-      - name: Upgrade pip
-        run: |
-          python -m pip install -U pip
-      - name: Install dependencies
-        run: |
-          python -m pip install '.[docs]'
-      - name: Auto-generate APIDOC sources
-        run: |-
-          sphinx-apidoc --output-dir docs/source/code --force .
-      - name: Create docs
-        run: |
-          make -C docs html
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          force_orphan: true
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/build/html
+    sphinx:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+        steps:
+            - uses: actions/checkout@v3
+              with:
+                  fetch-depth: 0
+            - uses: actions/setup-python@v4
+              with:
+                  cache: pip
+                  cache-dependency-path: pyproject.toml
+                  python-version: "3.12"
+            - name: Upgrade pip
+              run: python -m pip install -U pip
+            - name: Install dependencies
+              run: |
+                  sudo apt-get install -y pandoc
+                  python -m pip install '.[docs]'
+            - name: Auto-generate APIDOC sources
+              run: make -C docs apidoc
+            - name: Create docs
+              run: make -C docs html
+            - name: Archive the docs
+              # https://github.com/actions/upload-artifact#too-many-uploads-resulting-in-429-responses
+              run: (cd docs/build/html && zip -Xr ../html.zip .)
+            - name: Upload built docs as artifact
+              uses: actions/upload-artifact@v3
+              with:
+                  name: Documentation
+                  path: docs/build/html.zip
+                  if-no-files-found: error
+                  retention-days: 5
+            - name: Deploy
+              if: github.ref == 'refs/heads/master'
+              uses: peaceiris/actions-gh-pages@v3
+              with:
+                  force_orphan: true
+                  github_token: ${{ secrets.GITHUB_TOKEN }}
+                  publish_dir: ./docs/build/html

docs/source/howtos/howtos.rst

@@ -4,35 +4,35 @@
 
 .. _howtos:
 
-*******
+********
 Examples
-*******
+********
 
 This section contains a collection of examples that demonstrate how to use the library.
 
 Using the CLI
 =============
 
 Import ROS2 Messages:
-------------------------
+---------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i messages docs/source/examples/data/example_msgs -o capella docs/source/examples/data/empty_project_52 -l la --port 5000 --exists-action=k --no-deps
 
 Import ROS2 Messages from Git Repository:
-------------------------
+-----------------------------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i messages git+https://github.com/DSD-DBS/dsd-ros-msg-definitions-oss -o capella docs/source/examples/data/empty_project_52 -l la --port 5000 --exists-action=k
 
-Export Capella Model
----------------------
+Export Capella Model (experimental):
+------------------------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i capella docs/source/examples/data/melody_model_60 -l la -o messages docs/source/examples/data/example_msgs --port 5000
 
-Export Capella Model from Git Repository:
-------------------------
+Export Capella Model from Git Repository (experimental):
+--------------------------------------------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i capella git+https://github.com/DSD-DBS/coffee-machine -l la -o messages docs/source/examples/data/coffee_msgs --port 5000

docs/source/index.rst

@@ -3,16 +3,13 @@
    SPDX-License-Identifier: Apache-2.0
 
 
-*****************************
+***********************************************
 Welcome to the Capella ROS Tools documentation!
-*****************************
+***********************************************
 
 Overview
 ========
 
-.. image:: https://img.shields.io/badge/license-Apache%202-blue.svg
-   :target:
-
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
     :alt: Black
@@ -42,8 +39,8 @@ If you want a quickstart at how to use this tool, head right into the
 
 
 .. toctree::
+   :maxdepth: 3
    :caption: Examples
-   :titlesonly:
 
    howtos/howtos
 

docs/source/usage/usage.rst

@@ -2,7 +2,7 @@
    Copyright DB InfraGO AG and contributors
    SPDX-License-Identifier: Apache-2.0
 
-.. _howtos:
+.. _usage:
 
 *****
 Usage
@@ -11,13 +11,25 @@ Usage
 This section describes how to use the Capella ROS Tools CLI.
 
 Import ROS2 Messages:
-------------------------
+----------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i messages <ROS_MESSAGES_PATH> -o capella <CAPELLA_MODEL_PATH> -l <CAPELLA_MODEL_LAYER> --port=<PORT> --exists-action=<EXISTS_ACTION> --no-deps
 
-Export Capella Model
----------------------
+* "-i messages <ROS_MESSAGES_PATH>", import ROS2 messages from <ROS_MESSAGES_PATH>
+* "-o capella <CAPELLA_MODEL_PATH>", export to Capella model <CAPELLA_MODEL_PATH>
+* "-l <CAPELLA_MODEL_LAYER>", use Capella model layer <CAPELLA_MODEL_LAYER>
+* "--port=<PORT>", start Capella model server at <PORT>
+* "--exists-action=<EXISTS_ACTION>", action to take if a Capella element already exists
+* "--no-deps", do not import ROS2 dependencies (e.g. std_msgs)
+
+Export Capella Model (experimental):
+------------------------------------
 .. code-block:: bash
 
    $ python -m capella_ros_tools -i capella <CAPELLA_MODEL_PATH> -l <CAPELLA_MODEL_LAYER> -o messages <ROS_MESSAGES_PATH> --port <PORT>
+
+* "-i capella <CAPELLA_MODEL_PATH>", import Capella model from <CAPELLA_MODEL_PATH>
+* "-l <CAPELLA_MODEL_LAYER>", use Capella model layer <CAPELLA_MODEL_LAYER>
+* "-o messages <ROS_MESSAGES_PATH>", export ROS2 messages to <ROS_MESSAGES_PATH>
+* "--port=<PORT>", start Capella model server at <PORT>