From 1d094fccb816a2ed1ac7a2bc39e00fbc9cca9f0c Mon Sep 17 00:00:00 2001 From: huyenngn Date: Wed, 10 Jan 2024 09:05:56 +0100 Subject: [PATCH] docs: Install pandoc github action --- .github/workflows/docs.yml | 76 ++++++++++++++++++++--------------- docs/source/howtos/howtos.rst | 16 ++++---- docs/source/index.rst | 9 ++--- docs/source/usage/usage.rst | 8 ++-- 4 files changed, 59 insertions(+), 50 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d7e5095..16913ff 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/docs/source/howtos/howtos.rst b/docs/source/howtos/howtos.rst index 4d5e4ad..0d82cd1 100644 --- a/docs/source/howtos/howtos.rst +++ b/docs/source/howtos/howtos.rst @@ -4,9 +4,9 @@ .. _howtos: -******* +******** Examples -******* +******** This section contains a collection of examples that demonstrate how to use the library. @@ -14,25 +14,25 @@ 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 52eade7..ccdd1eb 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/usage/usage.rst b/docs/source/usage/usage.rst index 1c980f3..b81fbf6 100644 --- a/docs/source/usage/usage.rst +++ b/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,13 @@ 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 -o capella -l --port= --exists-action= --no-deps -Export Capella Model ---------------------- +Export Capella Model (experimental): +------------------------------------ .. code-block:: bash $ python -m capella_ros_tools -i capella -l -o messages --port