coverage and docs workflows

Summary: Relates to T15996

Reviewers: korina

Reviewed By: korina

Subscribers: miljen

Differential Revision: https://repo.mireo.local/D33719

.github/workflows/coverage.yml

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2023-2024 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
+# Copyright (c) 2023-2025 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
 #
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -9,13 +9,9 @@ name: coverage
 
 on: [push, pull_request]
 
-env:
-  BOOST_VERSION: 1.82.0
-  BOOST_DIR_VER_NAME: 1_82_0
-
 jobs:
   posix:
-    name: "coverage ${{ matrix.compiler }} -std=c++${{ matrix.cxxstd }} ${{ matrix.container }}"
+    name: "coverage ${{ matrix.toolset }} -std=c++${{ matrix.cxxstd }} ${{ matrix.container }}"
     defaults:
       run:
         shell: bash
@@ -24,10 +20,11 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - toolset: coverage
+          - toolset: gcc-11
-            compiler: g++-11
+            install: g++-11
             os: ubuntu-latest
             container: ubuntu:22.04
+            build-type: 'Coverage'
             cxxstd: 20
             cxxflags: '-g -O0 -std=c++20 --coverage -fkeep-inline-functions -fkeep-static-functions'
             ldflags: '--coverage'
@@ -35,6 +32,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     container: ${{ matrix.container }}
     env:
+      CXXFLAGS: ${{ matrix.cxxflags }}
+      LDFLAGS:  ${{ matrix.ldflags }}
       CMAKE_BUILD_PARALLEL_LEVEL: 4
 
     steps:
@@ -45,38 +44,34 @@ jobs:
         if: matrix.container
         run: |
           apt-get update
-          apt-get -y install sudo wget tar cmake openssl libssl-dev pkg-config lcov gpg git
+          apt-get -y install --no-install-recommends \
+            sudo git g++ cmake make openssl libssl-dev ca-certificates pkg-config \
+            python3 lcov gpg gpg-agent
 
       - name: Install compiler
-        run: sudo apt-get install -y ${{ matrix.compiler }}
+        run: sudo apt-get install -y ${{ matrix.install }}
       
       - name: Setup Boost
         run: |
-          wget https://archives.boost.io/release/${{ env.BOOST_VERSION }}/source/boost_${{ env.BOOST_DIR_VER_NAME }}.tar.gz
+          python3 tools/ci.py setup-boost \
-          tar xzf boost_${{ env.BOOST_DIR_VER_NAME }}.tar.gz
+            --source-dir=$(pwd)
-          mkdir /usr/local/boost_${{ env.BOOST_DIR_VER_NAME }}
-          mv boost_${{ env.BOOST_DIR_VER_NAME }}/boost /usr/local/boost_${{ env.BOOST_DIR_VER_NAME }}
-          rm boost_${{ env.BOOST_DIR_VER_NAME }}.tar.gz
 
-      - name: Setup library
+      - name: Build standalone tests using CMake
         run: |
-          cmake -S . -B build -DCMAKE_CXX_COMPILER="${{ matrix.compiler }}" \
+          python3 tools/ci.py build-cmake-standalone-tests \
-          -DBoost_INCLUDE_DIR="/usr/local/boost_${{ env.BOOST_DIR_VER_NAME }}"
+            --build-type ${{ matrix.build-type }} \
-          sudo cmake --install build
+            --cxxstd ${{ matrix.cxxstd }} \
+            --toolset ${{ matrix.toolset }}
 
-      - name: Build tests
+      - name: Run standalone tests
         run: |
-          cmake -S test -B test/build -DCMAKE_CXX_COMPILER="${{ matrix.compiler }}" -DCMAKE_CXX_FLAGS="${{ matrix.cxxflags }}" \
+          python3 tools/ci.py run-cmake-standalone-tests \
-          -DCMAKE_EXE_LINKER_FLAGS="${{ matrix.ldflags }}" -DCMAKE_BUILD_TYPE="Coverage" \
+           --build-type ${{ matrix.build-type }}
-          -DBoost_INCLUDE_DIR="/usr/local/boost_${{ env.BOOST_DIR_VER_NAME }}"
-          cmake --build test/build -j 4
-
-      - name: Run tests
-        run: ./test/build/mqtt-test
 
       - name: Generate Coverage Report
         run: |
-          lcov --capture --output-file coverage.info --directory test/build
+          lcov --capture --output-file coverage.info \
+            --directory ~/boost-root/libs/mqtt5/__build_standalone_tests__/test
           lcov --extract coverage.info '**/boost/mqtt5/*' --output-file coverage.info
 
       - name: Upload coverage reports to Codecov
@@ -88,3 +83,4 @@ jobs:
           fail_ci_if_error: true
           plugin: noop
           token: ${{ secrets.CODECOV_TOKEN }}
+          slug: mireo/async-mqtt5

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+#
+# Copyright (c) 2025 Ivica Siladic, Bruno Iljazovic, Korina Simicevic
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+name: docs
+
+on: [push]
+
+jobs:
+
+  posix:
+    name: "Docs ${{ matrix.container }}"
+
+    runs-on: ubuntu-latest
+    container: ubuntu:22.04
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup container environment
+        run: |
+          apt-get update
+          apt-get -y install --no-install-recommends \
+            doxygen docbook-xsl docutils-doc xsltproc wget ca-certificates g++ \
+            python3 python-is-python3 python3-jinja2 rsync git unzip
+
+      - name: Setup Boost
+        run: |
+          python3 tools/ci.py setup-boost \
+            --source-dir=$(pwd) \
+            --docs-install=1
+
+      - name: Build docs
+        run: |
+          python3 tools/ci.py build-docs

doc/qbk/00_main.qbk

@@ -22,12 +22,12 @@
 [template nochunk[] [block '''<?dbhtml stop-chunking?>''']]
 [template mdash[] '''&mdash; ''']
 [template hr[] '''<phrase role="silver">'''[mdash]'''</phrase>''']
-[template link_to_file[path][^'''<ulink url="https://github.com/mireo/async_mqtt5/blob/master/'''[path]'''">'''[path]'''</ulink>''']]
+[template link_to_file[path][^'''<ulink url="https://github.com/boostorg/mqtt5/blob/master/'''[path]'''">'''[path]'''</ulink>''']]
-[template include_file[path][^<'''<ulink url="https://github.com/mireo/async_mqtt5/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
+[template include_file[path][^<'''<ulink url="https://github.com/boostorg/mqtt5/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
 [template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
 [template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
 
-[template ghreflink[path text] [@https://github.com/mireo/async-mqtt5/blob/master/[path] [text]]]
+[template ghreflink[path text] [@https://github.com/boostorg/mqtt5/blob/master/[path] [text]]]
 [template reflink2[id text][link mqtt5.ref.boost__mqtt5__[id] [^[text]]]]
 [template reflink[id text][link mqtt5.ref.[id] [text]]]
 [template refmem[class mem][reflink2 [class].[mem] [class]::[mem]]]

test/CMakeLists.txt

@@ -10,36 +10,36 @@ project(boost_mqtt5_tests CXX)
 file(GLOB integration_tests "integration/*.cpp")
 file(GLOB unit_tests "unit/*.cpp")
 
-add_executable(mqtt-test src/run_tests.cpp ${integration_tests} ${unit_tests})
+add_executable(boost_mqtt5-tests src/run_tests.cpp ${integration_tests} ${unit_tests})
 
-target_include_directories(mqtt-test PRIVATE include)
+target_include_directories(boost_mqtt5-tests PRIVATE include)
-target_compile_definitions(mqtt-test PRIVATE BOOST_TEST_NO_MAIN=1)
+target_compile_definitions(boost_mqtt5-tests PRIVATE BOOST_TEST_NO_MAIN=1)
 
 if(BOOST_MQTT5_MAIN_PROJECT)
   find_package(OpenSSL REQUIRED)
-  target_compile_definitions(mqtt-test PRIVATE BOOST_MQTT5_EXTRA_DEPS=1)
+  target_compile_definitions(boost_mqtt5-tests PRIVATE BOOST_MQTT5_EXTRA_DEPS=1)
 
   target_link_libraries(
-    mqtt-test PRIVATE
+    boost_mqtt5-tests PRIVATE
     Boost::mqtt5
     OpenSSL::SSL
   )
 else()
   target_link_libraries(
-    mqtt-test PRIVATE
+    boost_mqtt5-tests PRIVATE
     Boost::mqtt5
     Boost::included_unit_test_framework
   )
 
   # Follow the Boost convention: don't build test targets by default,
   # and only when explicitly requested by building target tests
-  set_target_properties(mqtt-test PROPERTIES EXCLUDE_FROM_ALL ON)
+  set_target_properties(boost_mqtt5-tests PROPERTIES EXCLUDE_FROM_ALL ON)
-  add_dependencies(tests mqtt-test)
+  add_dependencies(tests boost_mqtt5-tests)
 endif()
 
 include(CTest)
-add_test(NAME mqtt-test COMMAND mqtt-test)
+add_test(NAME boost_mqtt5-tests COMMAND boost_mqtt5-tests)
 
 if (BOOST_MQTT5_PUBLIC_BROKER_TESTS)
-  set_property(TEST mqtt-test PROPERTY ENVIRONMENT "BOOST_MQTT5_PUBLIC_BROKER_TESTS=1")
+  set_property(TEST boost_mqtt5-tests PROPERTY ENVIRONMENT "BOOST_MQTT5_PUBLIC_BROKER_TESTS=1")
 endif()

tools/ci.py

@@ -93,7 +93,8 @@ def _deduce_boost_branch() -> str:
 # with the required dependencies, and leaves it at _boost_root. Places our library,
 # located under source_dir, under $BOOST_ROOT/libs. Also runs the bootstrap script so b2 is usable. 
 def _setup_boost(
-    source_dir: Path
+    source_dir: Path,
+    docs_install: bool = False
 ) -> None:
     assert source_dir.is_absolute()
     assert not _boost_root.exists()
@@ -113,10 +114,22 @@ def _setup_boost(
         ignore=ignore_patterns('__build*__', '.git')
     )
 
+    submodules = [
+        'libs/context',
+        'tools/boostdep',
+        'tools/boostbook',
+        'tools/docca',
+        'tools/quickbook'
+    ] if docs_install else [
+        'tools/boostdep'
+    ]
     # Install Boost dependencies
     _run(["git", "config", "submodule.fetchJobs", "8"])
-    _run(["git", "submodule", "update", "-q", "--init", "tools/boostdep"])
+    _run(["git", "submodule", "update", "-q", "--init"] + submodules)
-    _run(["python3", "tools/boostdep/depinst/depinst.py", "--include", "example", "mqtt5"])
+    if docs_install:
+        _run(['python3', 'tools/boostdep/depinst/depinst.py', '../tools/quickbook'])
+    else:
+        _run(["python3", "tools/boostdep/depinst/depinst.py", "--include", "example", "mqtt5"])
 
     # Bootstrap
     if _is_windows:
@@ -319,6 +332,18 @@ def _run_b2_tests(
     ])
 
 
+def _build_docs():
+    os.chdir(str(_boost_root))
+
+    # Write the config file
+    config_path = os.path.expanduser('~/user-config.jam')
+    with open(config_path, 'wt') as f:
+        f.writelines(['using doxygen ;\n', 'using boostbook ;\n'])
+
+    # Run b2
+    _run([_b2_command, 'libs/mqtt5/doc/'])
+
+
 def main():
     # Command line parsing
     parser = argparse.ArgumentParser()
@@ -326,6 +351,7 @@ def main():
 
     subp = subparsers.add_parser('setup-boost')
     subp.add_argument('--source-dir', type=Path, required=True)
+    subp.add_argument('--docs-install', type=_str2bool, required=False)
     subp.set_defaults(func=_setup_boost)
 
     subp = subparsers.add_parser('build-b2-distro')
@@ -384,6 +410,9 @@ def main():
     subp.add_argument('--toolset', default='gcc')
     subp.set_defaults(func=_run_b2_tests)
 
+    subp = subparsers.add_parser('build-docs')
+    subp.set_defaults(func=_build_docs)
+
     # Actually parse the arguments
     args = parser.parse_args()