diff --git a/.github/workflows/build_arduino.yml b/.github/workflows/build_arduino.yml index 1ebf029d..67d4bbad 100644 --- a/.github/workflows/build_arduino.yml +++ b/.github/workflows/build_arduino.yml @@ -12,44 +12,39 @@ on: - ".github/workflows/build_arduino.yml" - "examples/**" -env: - # convenient variable used multiple times - SKETCHES_REPORTS: sketches-reports - jobs: check_formatting: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 - # - name: Install clang-tools - # uses: KyleMayes/install-llvm-action@v1 - # with: - # version: 12 - - name: Install linter python package - run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1 - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --extensions=ino - - name: Linter checks failed? - if: steps.linter.outputs.checks-failed > 0 - run: exit 1 + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + ignore: '!examples|' + extensions: ino build: needs: check_formatting - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_arduino.yaml@main + with: + sketch-paths: | + - examples/RF24Mesh_Example + - examples/RF24Mesh_Example_Master_Statics + - examples/RF24Mesh_Example_Master_To_Nodes + - examples/RF24Mesh_Example_Node2Node + - examples/RF24Mesh_Example_Node2NodeExtra + - examples/RF24Mesh_SerialConfig + - examples/RF24Mesh_Example_Master + libraries: | + - source-url: https://github.com/nRF24/RF24.git + - source-url: https://github.com/nRF24/RF24Network.git + - source-path: ./ + fqbn: ${{ matrix.fqbn }} + enable-deltas-report: ${{ matrix.enable-deltas-report }} + platforms: | + - name: arduino:avr + - name: arduino:megaavr + - name: arduino:samd + - name: arduino:mbed + # - name: arduino:sam strategy: fail-fast: false - matrix: fqbn: - "arduino:avr:yun" @@ -75,7 +70,7 @@ jobs: - "arduino:avr:chiwawa" - "arduino:avr:one" - "arduino:avr:unowifi" - - "arduino:mbed:nano33ble" + # - "arduino:mbed:nano33ble" # pending nRF5x integration - "arduino:samd:mkr1000" - "arduino:samd:mkrwifi1010" - "arduino:samd:nano_33_iot" @@ -101,48 +96,8 @@ jobs: - fqbn: arduino:samd:mkrzero enable-deltas-report: true - steps: - - name: Checkout - uses: actions/checkout@v2 - - name: Compile examples - uses: arduino/compile-sketches@main - with: - sketch-paths: | - - examples/RF24Mesh_Example - - examples/RF24Mesh_Example_Master_Statics - - examples/RF24Mesh_Example_Master_To_Nodes - - examples/RF24Mesh_Example_Node2Node - - examples/RF24Mesh_Example_Node2NodeExtra - - examples/RF24Mesh_SerialConfig - - examples/RF24Mesh_Example_Master - libraries: | - - name: RF24 - - source-url: https://github.com/nRF24/RF24Network.git - - source-path: ./ - # - name: RF24Network - fqbn: ${{ matrix.fqbn }} - enable-deltas-report: ${{ matrix.enable-deltas-report }} - sketches-report-path: ${{ env.SKETCHES_REPORTS }} - # This step is needed to pass the size data to the report job - - name: Upload sketches report to workflow artifact - if: ${{ matrix.enable-deltas-report }} - uses: actions/upload-artifact@v2 - with: - name: ${{ env.SKETCHES_REPORTS }} - path: ${{ env.SKETCHES_REPORTS }} - # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report report: needs: [build] if: github.event_name == 'pull_request' - runs-on: ubuntu-latest - steps: - - name: Download sketches reports artifact - uses: actions/download-artifact@v2 - with: - name: ${{ env.SKETCHES_REPORTS }} - path: ${{ env.SKETCHES_REPORTS }} - - - uses: arduino/report-size-deltas@v1 - with: - sketches-reports-source: ${{ env.SKETCHES_REPORTS }} \ No newline at end of file + uses: nRF24/.github/.github/workflows/arduino_size_deltas.yaml@main diff --git a/.github/workflows/build_linux.yml b/.github/workflows/build_linux.yml index 14d4eb27..aa0c40f1 100644 --- a/.github/workflows/build_linux.yml +++ b/.github/workflows/build_linux.yml @@ -35,38 +35,22 @@ env: jobs: check_formatting: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 - # - name: Install clang-tools - # uses: KyleMayes/install-llvm-action@v1 - # with: - # version: 12 - - name: Install linter python package - run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1 - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --ignore='examples|examples_pico' - - name: Linter checks failed? - if: steps.linter.outputs.checks-failed > 0 - run: exit 1 + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + ignore: 'examples|examples_pico' using_cmake: needs: check_formatting - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_linux_cmake.yaml@main + with: + rf24mesh-ref: ${{ github.sha }} + compiler: ${{ matrix.toolchain.compiler }} + usr-dir: ${{ matrix.toolchain.usr_dir }} + examples-path: examples_RPi + deploy-release: ${{ github.event_name == 'release' && (matrix.toolchain.compiler == 'armhf' || matrix.toolchain.compiler == 'arm64') }} + py-wrapper-path: pyRF24Mesh strategy: fail-fast: false - matrix: toolchain: - compiler: "armhf" @@ -79,139 +63,3 @@ jobs: # usr_dir: "i686-linux-gnu" - compiler: "default" # github runner is hosted on a "amd64" usr_dir: "local" - - steps: - # - name: provide toolchain (for x86_64) - # if: ${{ matrix.toolchain.compiler == 'x86_64' }} - # run: | - # sudo apt-get update - # sudo apt-get install gcc-x86-64-linux-gnux32 g++-x86-64-linux-gnux32 - - # - name: provide toolchain (for i686) - # if: ${{ matrix.toolchain.compiler == 'i686' }} - # run: | - # sudo apt-get update - # sudo apt-get install gcc-i686-linux-gnu g++-i686-linux-gnu - - - name: provide toolchain (for arm64) - if: ${{ matrix.toolchain.compiler == 'arm64' }} - run: | - sudo apt-get update - sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: provide toolchain (for armhf) - if: ${{ matrix.toolchain.compiler == 'armhf' }} - run: | - sudo apt-get update - sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf - - - name: checkout RF24 - uses: actions/checkout@v2 - with: - repository: nRF24/RF24 - - - name: build & install RF24 - run: | - mkdir build - cd build - cmake .. -D CMAKE_BUILD_TYPE=$BUILD_TYPE -D RF24_DRIVER=SPIDEV \ - -D CMAKE_INSTALL_PREFIX=/usr/${{ matrix.toolchain.usr_dir }} \ - -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - sudo make install - - - name: checkout RF24Network - uses: actions/checkout@v2 - with: - repository: nRF24/RF24Network - - - name: build & install RF24Network - run: | - mkdir build - cd build - cmake .. -D CMAKE_BUILD_TYPE=$BUILD_TYPE \ - -D CMAKE_INSTALL_PREFIX=/usr/${{ matrix.toolchain.usr_dir }} \ - -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - sudo make install - - - name: checkout RF24Mesh repo - uses: actions/checkout@v2 - - - name: create CMake build environment - run: cmake -E make_directory ${{ github.workspace }}/build - - - name: configure lib - working-directory: ${{ github.workspace }}/build - run: | - cmake .. -D CMAKE_BUILD_TYPE=$BUILD_TYPE \ - -D CMAKE_INSTALL_PREFIX=/usr/${{ matrix.toolchain.usr_dir }} \ - -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - - - name: build lib - working-directory: ${{ github.workspace }}/build - run: cmake --build . - - - name: install lib - working-directory: ${{ github.workspace }}/build - run: sudo cmake --install . - - - name: package lib - working-directory: ${{ github.workspace }}/build - run: sudo cpack - - - name: Save artifact - uses: actions/upload-artifact@v2 - with: - name: "pkg_RF24Mesh" - path: | - ${{ github.workspace }}/build/pkgs/*.deb - ${{ github.workspace }}/build/pkgs/*.rpm - - - name: Upload Release assets - if: github.event_name == 'release' && (matrix.toolchain.compiler == 'armhf' || matrix.toolchain.compiler == 'arm64') - uses: csexton/release-asset-action@master - with: - pattern: "${{ github.workspace }}/build/pkgs/librf24*" - github-token: ${{ secrets.GITHUB_TOKEN }} - - - name: clean build environment - working-directory: ${{ github.workspace }}/build - run: sudo rm -r ./* - - - name: configure examples - working-directory: ${{ github.workspace }}/build - run: | - cmake ../examples_RPi \ - -D CMAKE_TOOLCHAIN_FILE=../cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - - - name: build examples - working-directory: ${{ github.workspace }}/build - # doesn't build the RF24Mesh_Ncurses_Master example because we haven't cross-compiled it in this workflow - run: | - cmake --build . - file ./RF24Mesh_Example - - # cross-compiling a python C extension is better done with pypa/cibuildwheel action - - name: Set up Python 3.7 - if: ${{ matrix.toolchain.compiler == 'default' }} - uses: actions/setup-python@v1 - with: - python-version: 3.7 - - - name: provide python wrapper prerequisites - if: ${{ matrix.toolchain.compiler == 'default' }} - # python3-rpi.gpio is only required for physical hardware (namely the IRQ example) - run: sudo apt-get install python3-dev libboost-python-dev python3-setuptools - - - name: create alias symlink to libboost_python3*.so - if: ${{ matrix.toolchain.compiler == 'default' }} - run: sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so - - - name: build python wrapper - if: ${{ matrix.toolchain.compiler == 'default' }} - working-directory: ${{ github.workspace }}/pyRF24Mesh - run: python3 setup.py build - - - name: install python wrapper - if: ${{ matrix.toolchain.compiler == 'default' }} - working-directory: ${{ github.workspace }}/pyRF24Mesh - run: sudo python3 setup.py install diff --git a/.github/workflows/build_platformIO.yml b/.github/workflows/build_platformIO.yml index 3b5885a3..a86325a9 100644 --- a/.github/workflows/build_platformIO.yml +++ b/.github/workflows/build_platformIO.yml @@ -21,79 +21,22 @@ on: jobs: validate_lib_json: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - - - name: get latest release version number - id: latest_ver - run: echo "::set-output name=release::$(awk -F "=" '/version/ {print $2}' library.properties)" - - - name: Set up Python - uses: actions/setup-python@v2 - - - name: Install PlatformIO - run: | - python -m pip install --upgrade pip - pip install --upgrade platformio - - - name: package lib - run: pio package pack -o PlatformIO-RF24Mesh-${{ steps.latest_ver.outputs.release }}.tar.gz - - - name: Save artifact - uses: actions/upload-artifact@v2 - with: - name: "PIO_pkg_RF24Mesh" - path: PlatformIO*.tar.gz - - - name: Upload Release assets - if: github.event_name == 'release' - uses: csexton/release-asset-action@master - with: - pattern: "PlatformIO*.tar.gz" - github-token: ${{ secrets.GITHUB_TOKEN }} - - - name: upload package to PlatformIO Registry - if: github.event_name == 'release' && github.event_type != 'edited' - # PIO lib packages cannot be re-published under the same tag - env: - PLATFORMIO_AUTH_TOKEN: ${{ secrets.PLATFORMIO_AUTH_TOKEN }} - run: pio package publish --owner nrf24 --non-interactive + uses: nRF24/.github/.github/workflows/validate_deploy_platformio.yaml@main + secrets: inherit check_formatting: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 - # - name: Install clang-tools - # uses: KyleMayes/install-llvm-action@v1 - # with: - # version: 12 - - name: Install linter python package - run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1 - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --extensions=ino - - name: Linter checks failed? - if: steps.linter.outputs.checks-failed > 0 - run: exit 1 + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + extensions: ino build: needs: [check_formatting, validate_lib_json] - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_platformio.yaml@main + with: + example-path: ${{ matrix.example }} + board-id: ${{ matrix.board }} strategy: fail-fast: false - matrix: example: - "examples/RF24Mesh_Example/RF24Mesh_Example.ino" @@ -110,41 +53,3 @@ jobs: - "teensy40" - "teensy41" - "teensylc" - - steps: - - uses: actions/checkout@v2 - - - name: Cache pip - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Cache PlatformIO - uses: actions/cache@v2 - with: - path: ~/.platformio - key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} - - - name: Set up Python - uses: actions/setup-python@v2 - - - name: Install PlatformIO - run: | - python -m pip install --upgrade pip - pip install --upgrade platformio - - # "dependencies" field in JSON should automatically install RF24 & RF24Network. - # Because we run this CI test against the local repo, the JSON seems neglected - - name: Install library dependencies - run: | - pio lib -g install nrf24/RF24 - pio lib -g install https://github.com/nrf24/RF24Network.git - # pio lib -g install nrf24/RF24Network - - - name: Run PlatformIO - run: pio ci --lib="." --board=${{ matrix.board }} - env: - PLATFORMIO_CI_SRC: ${{ matrix.example }} diff --git a/.github/workflows/build_rp2xxx.yml b/.github/workflows/build_rp2xxx.yml index 3e5db046..f6ae05a9 100644 --- a/.github/workflows/build_rp2xxx.yml +++ b/.github/workflows/build_rp2xxx.yml @@ -19,44 +19,20 @@ on: - "cmake/**" - "examples_pico/*" -env: - # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.) - BUILD_TYPE: Release - jobs: check_formatting: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 - # - name: Install clang-tools - # uses: KyleMayes/install-llvm-action@v1 - # with: - # version: 12 - - name: Install linter python package - run: python3 -m pip install git+https://github.com/cpp-linter/cpp-linter-action@v1 - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --ignore='!examples_pico|' - - name: Linter checks failed? - if: steps.linter.outputs.checks-failed > 0 - run: exit 1 + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + ignore: '!examples_pico|' build: needs: check_formatting - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_pico_sdk.yaml@main + with: + board-id: ${{ matrix.board }} + rf24mesh-ref: ${{ github.sha }} strategy: fail-fast: false - matrix: board: - "pico" @@ -74,64 +50,3 @@ jobs: - "pimoroni_pga2040" # requires PicoSDK v1.2.0 # - "pimoroni_keybow2040" # no SPI bus exposed # - "pimoroni_picosystem" # SPI is reserved for LCD - - steps: - - name: checkout RF24Mesh lib - uses: actions/checkout@v2 - with: - path: RF24Mesh - - - name: checkout RF24Network lib - uses: actions/checkout@v2 - with: - repository: nRF24/RF24Network - path: RF24Network - - - name: checkout RF24 lib - uses: actions/checkout@v2 - with: - repository: nRF24/RF24 - path: RF24 - - - name: Install toolchain - run: sudo apt update && sudo apt install gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential - - - name: Clone pico-sdk - uses: actions/checkout@v2 - with: - repository: raspberrypi/pico-sdk - # master branch is latest stable release - path: pico-sdk - clean: false - submodules: true - - - name: Checkout pico-sdk submodules - working-directory: ${{ github.workspace }}/pico-sdk - run: git submodule update --init - - - name: Create Build Environment - working-directory: ${{ github.workspace }}/RF24Mesh - env: - PICO_SDK_PATH: ${{ github.workspace }}/pico-sdk - run: cmake -E make_directory ${{ github.workspace }}/RF24Mesh/build - - - name: Configure CMake - working-directory: ${{ github.workspace }}/RF24Mesh/build - env: - PICO_SDK_PATH: ${{ github.workspace }}/pico-sdk - run: cmake ../examples_pico -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DPICO_BOARD=${{ matrix.board }} - - - name: Build - working-directory: ${{ github.workspace }}/RF24Mesh/build - # Execute the build. You can specify a specific target with "--target " - run: cmake --build . --config $BUILD_TYPE - - - name: Save artifact - uses: actions/upload-artifact@v2 - with: - name: examples_pico_${{ matrix.board }} - path: | - ${{ github.workspace }}/RF24Mesh/build/*.uf2 - ${{ github.workspace }}/RF24Mesh/build/*.elf - # ${{ github.workspace }}/RF24Mesh/build/*.hex - # ${{ github.workspace }}/RF24Mesh/build/*.bin diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 72e7ca8b..a81874e4 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -32,53 +32,8 @@ on: workflow_dispatch: jobs: - build-doxygen: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - - name: get latest release version number - id: latest_ver - run: echo "::set-output name=release::$(awk -F "=" '/version/ {print $2}' library.properties)" - - name: overwrite doxygen tags - run: | - touch doxygenAction - echo "PROJECT_NUMBER = ${{ steps.latest_ver.outputs.release }}" >> doxygenAction - echo "@INCLUDE = doxygenAction" >> Doxyfile - - name: install Doxygen static libclang deps - run: sudo apt-get install libclang1-9 libclang-cpp9 - - name: install doxygen from SF binary archives - env: - DOXYGEN_VERSION: '1.9.4' - run: | - mkdir doxygen && cd doxygen - curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz - gunzip doxygen.tar.gz - tar xf doxygen.tar - cd doxygen-$DOXYGEN_VERSION - sudo make install - - run: doxygen - - name: Save doxygen docs as artifact - uses: actions/upload-artifact@v2 - with: - name: "RF24Mesh_doxygen_docs" - path: ${{ github.workspace }}/docs/html - - name: upload to github pages - if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/html - - # build pretty docs using doxygen XML output with Sphinx - - uses: actions/setup-python@v2 - - name: Install sphinx deps - run: python -m pip install -r docs/sphinx/requirements.txt - - name: build docs with Sphinx - working-directory: docs - run: sphinx-build sphinx _build - - name: Save sphinx docs as artifact - uses: actions/upload-artifact@v2 - with: - name: "RF24Mesh_sphinx_docs" - path: ${{ github.workspace }}/docs/_build + build-docs: + uses: nRF24/.github/.github/workflows/build_docs.yaml@main + with: + deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }} + secrets: inherit diff --git a/.gitignore b/.gitignore index 4cff0cb3..1db888b5 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,10 @@ build/ # ignore PlatformIO packages *.tar.gz +# ignore python venv +.env/ +.venv/ + # Cmake build-in-source generated stuff CMakeCache.txt CPackConfig.cmake diff --git a/Doxyfile b/docs/Doxyfile similarity index 92% rename from Doxyfile rename to docs/Doxyfile index cb305fd8..e56a0239 100644 --- a/Doxyfile +++ b/docs/Doxyfile @@ -36,7 +36,18 @@ PROJECT_BRIEF = "TMRh20 2020 - A user friendly mesh overlay for sensor # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./docs +OUTPUT_DIRECTORY = ./ + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand part +# of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to strip. +# Note that you can specify absolute paths here, but also relative paths, which will +# be relative from the directory where doxygen is started. +# +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = ../ # This tag implements a quasi-intelligent brief description abbreviator that is # used to form the text in various listings. Each string in this list, if found @@ -172,8 +183,8 @@ WARN_AS_ERROR = YES # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ./ \ - ./docs/ +INPUT = ../ \ + ./ # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and @@ -261,8 +272,8 @@ EXCLUDE_SYMBOLS = _ # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = examples \ - examples_RPi +EXAMPLE_PATH = ../examples \ + ../examples_RPi # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands @@ -275,14 +286,14 @@ EXAMPLE_RECURSIVE = YES # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = images +IMAGE_PATH = ../images # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = ./docs/main_page.md +USE_MDFILE_AS_MAINPAGE = main_page.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -314,6 +325,24 @@ SOURCE_BROWSER = YES HTML_EXTRA_STYLESHEET = doxygen-custom.css +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output should be rendered +# with a dark or light theme. +# +# Possible values are: +# - LIGHT always generate light mode output +# - DARK always generate dark mode output +# - AUTO_LIGHT automatically set the mode according to the user preference, +# use light mode if no preference is set (the default) +# - AUTO_DARK automatically set the mode according to the user preference, +# use dark mode if no preference is set +# - TOGGLE allow to user to switch between light and dark mode via a button. +# +# The default value is: AUTO_LIGHT. +# +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE = TOGGLE + # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this # to YES can help to show when doxygen was last run and thus if the diff --git a/docs/README.md b/docs/README.md index 1fa6589c..fbbc75e1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1 +1,39 @@ -These markdown files (*.md) contain relative hyperlinks. Any relative hyperlinks will not work when viewing these markdown files in github. \ No newline at end of file +# Please browse the docs from either http://nrf24.github.io/RF24Mesh or https://rf24mesh.rtfd.io + +## Intended for use in Doxygen + +The markdown files (\*.md) in this docs folder contain relative hyperlinks. Any relative hyperlinks will not work when viewing these markdown files in github. + +---- + +## Building the docs + +Navigate to the repo's docs folder: + +```shell +cd docs +``` + +Install Doxygen (v1.9.5 or newer) and run the following command from the repo's docs folder: + +```shell +doxygen +``` + +The Doxygen HTML output is now in docs/html. The Doxygen XML output in docs/sphinx/xml can be optionally used to generate Sphinx output. + +### Generating Sphinx docs (optional) + +To build the Sphinx docs based on Doxygen's XML output, first install the necessary python dependencies. + +``` shell +python -m pip install docs/sphinx/requirements.txt +``` + +Now build the Sphinx docs (after building the Doxygen output) from the repo's docs folder: + +```shell +sphinx-build sphinx _build/html +``` + +The Sphinx HTML output now exists in docs/_build/html. diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css new file mode 100644 index 00000000..7d56191d --- /dev/null +++ b/docs/doxygen-custom.css @@ -0,0 +1,3 @@ +table.markdownTable th { + color: unset; +} diff --git a/docs/general_usage.md b/docs/general_usage.md index 403d7f38..e2fa2c74 100644 --- a/docs/general_usage.md +++ b/docs/general_usage.md @@ -1,5 +1,7 @@ # General Usage - + +@tableofcontents + ## Network Design Options 1. **Static Network** (No Mesh) diff --git a/docs/main_page.md b/docs/main_page.md index 4e1115d5..c8e9bf10 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -1,5 +1,7 @@ # Mesh Networking Layer for RF24 Radios +@tableofcontents + This class intends to provide a simple and seamless 'mesh' layer for sensor networks, allowing automatic and dynamic configuration that can be customized to suit many scenarios. It is currently designed to interface directly with with the diff --git a/docs/setup_config.md b/docs/setup_config.md index daacdfd9..808cc236 100644 --- a/docs/setup_config.md +++ b/docs/setup_config.md @@ -1,5 +1,7 @@ # Setup And Config +@tableofcontents + The initial testing version of RF24Mesh is built as a simple overlay for RF24Network. Users currently need to be familiar with the basics of sending and receiving data via RF24Network, but do not need to understand the topology, routing or addressing systems. diff --git a/docs/sphinx/_static/custom_material.css b/docs/sphinx/_static/custom_material.css index 61e7b017..dd7e9fe2 100644 --- a/docs/sphinx/_static/custom_material.css +++ b/docs/sphinx/_static/custom_material.css @@ -1,51 +1,3 @@ -.md-typeset .admonition, -.md-typeset details { - font-size: 0.75rem; -} - -.md-typeset .admonition.tip>.admonition-title::before, -.md-typeset .admonition.hint>.admonition-title::before { - mask-image: url('data:image/svg+xml;charset=utf-8,'); -} - -.md-typeset .admonition.seealso>.admonition-title::before { - mask-image: url('data:image/svg+xml;charset=utf-8,'); - background-color: hsl(301, 100%, 63%); -} - -.md-typeset .admonition.seealso { - border-left: .2rem solid hsl(301, 100%, 63%); -} - -.md-typeset .admonition.seealso>.admonition-title { - background-color: hsla(287, 100%, 63%, 0.25); -} - -.md-typeset .admonition.important>.admonition-title::before { - mask-image: url('data:image/svg+xml;charset=utf-8,'); - background-color: hsl(123, 100%, 63%); -} - -.md-typeset .admonition.important { - border-left: .2rem solid hsl(123, 100%, 63%); -} - -.md-typeset .admonition.important>.admonition-title { - background-color: hsla(123, 100%, 63%, 0.25); -} - -.md-typeset .admonition.warning>.admonition-title::before { - background-color: hsl(0, 100%, 63%); -} - -.md-typeset .admonition.warning { - border-left: .2rem solid hsl(0, 100%, 63%); -} - -.md-typeset .admonition.warning>.admonition-title { - background-color: hsla(0, 100%, 63%, 0.25); -} - html .md-nav--primary .md-nav__title--site .md-nav__button { top: 0; left: 0; @@ -53,17 +5,9 @@ html .md-nav--primary .md-nav__title--site .md-nav__button { height: auto; } -.md-typeset table:not([class]) th { - background-color: rgba(23, 35, 83, 0.8); -} - -.md-typeset table:not([class]) tr:hover { - background-color: rgba(56, 2, 81, 0.8); - box-shadow: inset 0 .05rem 0 #9515ff; -} - -[data-md-color-scheme="default"] { - --md-code-bg-color: #e8e7e7; +thead { + background-color: var(--md-default-fg-color--light); + color: var(--md-primary-bg-color); } .md-nav__title .md-nav__button.md-logo img, .md-nav__title .md-nav__button.md-logo svg { @@ -74,20 +18,3 @@ html .md-nav--primary .md-nav__title--site .md-nav__button { .md-header__button.md-logo img, .md-header__button.md-logo svg { width: auto; } - -/* CSS for Remark admonitions (translated by breathe from doxygen's @remark(s) cmd */ -:root { - --md-admonition-icon--remark: url('data:image/svg+xml;charset=utf-8,') -} -.md-typeset .admonition.remark { - border-color: rgb(116, 66, 255); -} -.md-typeset .remark > .admonition-title { - background-color: rgba(116, 66, 255, 0.1); - border-color: rgb(116, 66, 255); -} -.md-typeset .remark > .admonition-title::before { - background-color: rgb(116, 66, 255); - -webkit-mask-image: var(--md-admonition-icon--remark); - mask-image: var(--md-admonition-icon--remark); -} diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 712e2cd4..e76f566a 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -82,7 +82,7 @@ READTHEDOCS = os.environ.get("READTHEDOCS", None) == "True" if READTHEDOCS: - subprocess.call("cd ../..; doxygen", shell=True) + subprocess.call("cd ..; doxygen", shell=True) # -- Options for HTML output ------------------------------------------------- @@ -137,6 +137,32 @@ ("cpp:function", dict(include_fields_in_toc=False)), ] +sphinx_immaterial_custom_admonitions = [ + { + "name": "warning", + "color": (255, 66, 66), + "icon": "octicons/alert-24", + "override": True, + }, + { + "name": "note", + "icon": "octicons/pencil-24", + "override": True, + }, + { + "name": "seealso", + "color": (255, 66, 252), + "icon": "octicons/eye-24", + "title": "See Also", + "override": True, + }, + { + "name": "remark", + "color": (116, 66, 255), + "icon": "octicons/checklist-16", + }, +] + # Set link name generated in the top bar. html_title = "RF24Mesh C++ library" diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 716d1e25..2283f6de 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -1,5 +1,5 @@ -:hero: Automated Networking for nrf24L01 radios +:hero: Mesh Networking Layer for nRF24L01 radios Introduction ============= diff --git a/doxygen-custom.css b/doxygen-custom.css deleted file mode 100644 index 236f3e3b..00000000 --- a/doxygen-custom.css +++ /dev/null @@ -1,815 +0,0 @@ -/* The standard CSS for doxygen */ - -body, table, div, p, dl { - font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif; - font-size: 12px; -} - -/* @group Heading Levels */ - -h1 { - font-size: 150%; -} - -.title { - font-size: 150%; - font-weight: bold; - margin: 10px 2px; -} - -h2 { - font-size: 120%; -} - -h3 { - font-size: 100%; -} - -dt { - font-weight: bold; -} - -div.multicol { - -moz-column-gap: 1em; - -webkit-column-gap: 1em; - -moz-column-count: 3; - -webkit-column-count: 3; -} - -p.startli, p.startdd, p.starttd { - margin-top: 2px; -} - -p.endli { - margin-bottom: 0px; -} - -p.enddd { - margin-bottom: 4px; -} - -p.endtd { - margin-bottom: 2px; -} - -/* @end */ - -caption { - font-weight: bold; -} - -span.legend { - font-size: 70%; - text-align: center; -} - -h3.version { - font-size: 90%; - text-align: center; -} - -div.qindex, div.navtab { - background-color: #EBEFF6; - border: 1px solid #A3B4D7; - text-align: center; - margin: 2px; - padding: 2px; -} - -div.qindex, div.navpath { - width: 100%; - line-height: 110%; -} - -div.navtab { - margin-right: 15px; -} - -/* @group Link Styling */ - -a { - color: #3D578C; - font-weight: normal; - text-decoration: none; -} - -.contents a:visited { - color: #4665A2; -} - -a:hover { - text-decoration: underline; -} - -a.qindex { - font-weight: bold; -} - -a.qindexHL { - font-weight: bold; - background-color: #9CAFD4; - color: #ffffff; - border: 1px double #869DCA; -} - -.contents a.qindexHL:visited { - color: #ffffff; -} - -a.el { - font-weight: bold; -} - -a.elRef { -} - -a.code { - color: #4665A2; -} - -a.codeRef { - color: #4665A2; -} - -/* @end */ - -dl.el { - margin-left: -1cm; -} - -.fragment { - font-family: monospace, fixed; - font-size: 105%; -} - -pre.fragment { - border: 1px solid #C4CFE5; - background-color: #FBFCFD; - padding: 4px 6px; - margin: 4px 8px 4px 2px; - overflow: auto; - word-wrap: break-word; - font-size: 9pt; - line-height: 125%; -} - -div.ah { - background-color: black; - font-weight: bold; - color: #ffffff; - margin-bottom: 3px; - margin-top: 3px; - padding: 0.2em; - border: solid thin #333; - border-radius: 0.5em; - -webkit-border-radius: .5em; - -moz-border-radius: .5em; - box-shadow: 2px 2px 3px #999; - -webkit-box-shadow: 2px 2px 3px #999; - -moz-box-shadow: rgba(0, 0, 0, 0.15) 2px 2px 2px; - background-image: -webkit-gradient(linear, left top, left bottom, from(#eee), to(#000), color-stop(0.3, #444)); - background-image: -moz-linear-gradient(center top, #eee 0%, #444 40%, #000); -} - -div.groupHeader { - margin-left: 16px; - margin-top: 12px; - font-weight: bold; -} - -div.groupText { - margin-left: 16px; - font-style: italic; -} - -body { - background: white; - color: black; - margin: 0; -} - -div.contents { - margin-top: 10px; - margin-left: 10px; - margin-right: 5px; -} - -td.indexkey { - background-color: #EBEFF6; - font-weight: bold; - border: 1px solid #C4CFE5; - margin: 2px 0px 2px 0; - padding: 2px 10px; -} - -td.indexvalue { - background-color: #EBEFF6; - border: 1px solid #C4CFE5; - padding: 2px 10px; - margin: 2px 0px; -} - -tr.memlist { - background-color: #EEF1F7; -} - -p.formulaDsp { - text-align: center; -} - -img.formulaDsp { - -} - -img.formulaInl { - vertical-align: middle; -} - -div.center { - text-align: center; - margin-top: 0px; - margin-bottom: 0px; - padding: 0px; -} - -div.center img { - border: 0px; -} - -address.footer { - text-align: right; - padding-right: 12px; -} - -img.footer { - border: 0px; - vertical-align: middle; -} - -/* @group Code Colorization */ - -span.keyword { - color: #008000 -} - -span.keywordtype { - color: #604020 -} - -span.keywordflow { - color: #e08000 -} - -span.comment { - color: #800000 -} - -span.preprocessor { - color: #806020 -} - -span.stringliteral { - color: #002080 -} - -span.charliteral { - color: #008080 -} - -span.vhdldigit { - color: #ff00ff -} - -span.vhdlchar { - color: #000000 -} - -span.vhdlkeyword { - color: #700070 -} - -span.vhdllogic { - color: #ff0000 -} - -/* @end */ - -/* -.search { - color: #003399; - font-weight: bold; -} - -form.search { - margin-bottom: 0px; - margin-top: 0px; -} - -input.search { - font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #e8eef2; -} -*/ - -td.tiny { - font-size: 75%; -} - -.dirtab { - padding: 4px; - border-collapse: collapse; - border: 1px solid #A3B4D7; -} - -th.dirtab { - background: #EBEFF6; - font-weight: bold; -} - -hr { - height: 0px; - border: none; - border-top: 1px solid #4A6AAA; -} - -hr.footer { - height: 1px; -} - -/* @group Member Descriptions */ - -table.memberdecls { - border-spacing: 0px; - padding: 0px; -} - -.mdescLeft, .mdescRight, -.memItemLeft, .memItemRight, -.memTemplItemLeft, .memTemplItemRight, .memTemplParams { - background-color: #F9FAFC; - border: none; - margin: 4px; - padding: 1px 0 0 8px; -} - -.mdescLeft, .mdescRight { - padding: 0px 8px 4px 8px; - color: #555; -} - -.memItemLeft, .memItemRight, .memTemplParams { - border-top: 1px solid #C4CFE5; -} - -.memItemLeft, .memTemplItemLeft { - white-space: nowrap; -} - -.memItemRight { - width: 100%; -} - -.memTemplParams { - color: #4665A2; - white-space: nowrap; -} - -/* @end */ - -/* @group Member Details */ - -/* Styles for detailed member documentation */ - -.memtemplate { - font-size: 80%; - color: #4665A2; - font-weight: normal; - margin-left: 9px; -} - -.memnav { - background-color: #EBEFF6; - border: 1px solid #A3B4D7; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} - -.mempage { - width: 100%; -} - -.memitem { - padding: 0; - margin-bottom: 10px; - margin-right: 5px; -} - -.memname { - white-space: nowrap; - font-weight: bold; - margin-left: 6px; -} - -.memproto { - border-top: 1px solid #A8B8D9; - border-left: 1px solid #A8B8D9; - border-right: 1px solid #A8B8D9; - padding: 6px 0px 6px 0px; - color: #253555; - font-weight: bold; - text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); - /* opera specific markup */ - box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - border-top-right-radius: 8px; - border-top-left-radius: 8px; - /* firefox specific markup */ - -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; - -moz-border-radius-topright: 8px; - -moz-border-radius-topleft: 8px; - /* webkit specific markup */ - -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - -webkit-border-top-right-radius: 8px; - -webkit-border-top-left-radius: 8px; - background-image: url('nav_f.png'); - background-repeat: repeat-x; - background-color: #E2E8F2; - -} - -.memdoc { - border-bottom: 1px solid #A8B8D9; - border-left: 1px solid #A8B8D9; - border-right: 1px solid #A8B8D9; - padding: 2px 5px; - background-color: #FBFCFD; - border-top-width: 0; - /* opera specific markup */ - border-bottom-left-radius: 8px; - border-bottom-right-radius: 8px; - box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - /* firefox specific markup */ - -moz-border-radius-bottomleft: 8px; - -moz-border-radius-bottomright: 8px; - -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; - background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 60%, #F7F8FB 95%, #EEF1F7); - /* webkit specific markup */ - -webkit-border-bottom-left-radius: 8px; - -webkit-border-bottom-right-radius: 8px; - -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - background-image: -webkit-gradient(linear, center top, center bottom, from(#FFFFFF), color-stop(0.6, #FFFFFF), color-stop(0.60, #FFFFFF), color-stop(0.95, #F7F8FB), to(#EEF1F7)); -} - -.paramkey { - text-align: right; -} - -.paramtype { - white-space: nowrap; -} - -.paramname { - color: #602020; - white-space: nowrap; -} - -.paramname em { - font-style: normal; -} - -.params, .retval, .exception, .tparams { - border-spacing: 6px 2px; -} - -.params .paramname, .retval .paramname { - font-weight: bold; - vertical-align: top; -} - -.params .paramtype { - font-style: italic; - vertical-align: top; -} - -.params .paramdir { - font-family: "courier new", courier, monospace; - vertical-align: top; -} - - -/* @end */ - -/* @group Directory (tree) */ - -/* for the tree view */ - -.ftvtree { - font-family: sans-serif; - margin: 0px; -} - -/* these are for tree view when used as main index */ - -.directory { - font-size: 9pt; - font-weight: bold; - margin: 5px; -} - -.directory h3 { - margin: 0px; - margin-top: 1em; - font-size: 11pt; -} - -/* -The following two styles can be used to replace the root node title -with an image of your choice. Simply uncomment the next two styles, -specify the name of your image and be sure to set 'height' to the -proper pixel height of your image. -*/ - -/* -.directory h3.swap { - height: 61px; - background-repeat: no-repeat; - background-image: url("yourimage.gif"); -} -.directory h3.swap span { - display: none; -} -*/ - -.directory > h3 { - margin-top: 0; -} - -.directory p { - margin: 0px; - white-space: nowrap; -} - -.directory div { - display: none; - margin: 0px; -} - -.directory img { - vertical-align: -30%; -} - -/* these are for tree view when not used as main index */ - -.directory-alt { - font-size: 100%; - font-weight: bold; -} - -.directory-alt h3 { - margin: 0px; - margin-top: 1em; - font-size: 11pt; -} - -.directory-alt > h3 { - margin-top: 0; -} - -.directory-alt p { - margin: 0px; - white-space: nowrap; -} - -.directory-alt div { - display: none; - margin: 0px; -} - -.directory-alt img { - vertical-align: -30%; -} - -/* @end */ - -div.dynheader { - margin-top: 8px; -} - -address { - font-style: normal; - color: #2A3D61; -} - -table.doxtable { - border-collapse: collapse; -} - -table.doxtable td, table.doxtable th { - border: 1px solid #2D4068; - padding: 3px 7px 2px; -} - -table.doxtable th { - background-color: #374F7F; - color: #FFFFFF; - font-size: 110%; - padding-bottom: 4px; - padding-top: 5px; - text-align: left; -} - -.tabsearch { - top: 0px; - left: 10px; - height: 36px; - background-image: url('tab_b.png'); - z-index: 101; - overflow: hidden; - font-size: 13px; -} - -.navpath ul { - font-size: 11px; - background-image: url('tab_b.png'); - background-repeat: repeat-x; - height: 30px; - line-height: 30px; - color: #8AA0CC; - border: solid 1px #C2CDE4; - overflow: hidden; - margin: 0px; - padding: 0px; -} - -.navpath li { - list-style-type: none; - float: left; - padding-left: 10px; - padding-right: 15px; - background-image: url('bc_s.png'); - background-repeat: no-repeat; - background-position: right; - color: #364D7C; -} - -.navpath li.navelem a { - height: 32px; - display: block; - text-decoration: none; - outline: none; -} - -.navpath li.navelem a:hover { - color: #6884BD; -} - -.navpath li.footer { - list-style-type: none; - float: right; - padding-left: 10px; - padding-right: 15px; - background-image: none; - background-repeat: no-repeat; - background-position: right; - color: #364D7C; - font-size: 8pt; -} - - -div.summary { - float: right; - font-size: 8pt; - padding-right: 5px; - width: 50%; - text-align: right; -} - -div.summary a { - white-space: nowrap; -} - -div.ingroups { - font-size: 8pt; - padding-left: 5px; - width: 50%; - text-align: left; -} - -div.ingroups a { - white-space: nowrap; -} - -div.header { - background-image: url('nav_h.png'); - background-repeat: repeat-x; - background-color: #F9FAFC; - margin: 0px; - border-bottom: 1px solid #C4CFE5; -} - -div.headertitle { - padding: 5px 5px 5px 10px; -} - -dl { - padding: 0 0 0 10px; -} - -dl.note, dl.warning, dl.attention, dl.pre, dl.post, dl.invariant, dl.deprecated, dl.todo, dl.test, dl.bug { - border-left: 4px solid; - padding: 0 0 0 6px; -} - -dl.note { - border-color: #D0C000; -} - -dl.warning, dl.attention { - border-color: #FF0000; -} - -dl.pre, dl.post, dl.invariant { - border-color: #00D000; -} - -dl.deprecated { - border-color: #505050; -} - -dl.todo { - border-color: #00C0E0; -} - -dl.test { - border-color: #3030E0; -} - -dl.bug { - border-color: #C08050; -} - -#projectlogo { - text-align: center; - vertical-align: bottom; - border-collapse: separate; -} - -#projectlogo img { - border: 0px none; -} - -#projectname { - font: 300% Tahoma, Arial, sans-serif; - margin: 0px; - padding: 2px 0px; -} - -#projectbrief { - font: 120% Tahoma, Arial, sans-serif; - margin: 0px; - padding: 0px; -} - -#projectnumber { - font: 50% Tahoma, Arial, sans-serif; - margin: 0px; - padding: 0px; -} - -#titlearea { - padding: 0px; - margin: 0px; - width: 100%; - border-bottom: 1px solid #5373B4; -} - -.image { - text-align: left; -} - -.dotgraph { - text-align: center; -} - -.mscgraph { - text-align: center; -} - -.caption { - font-weight: bold; -} -td.fielddoc -th.markdownTableHeadLeft, -th.markdownTableHeadRight, -th.markdownTableHeadCenter, -th.markdownTableHeadNone { - background-image: none; - border-radius: unset; -} - -td.fielddoc tr:last-child { - border-bottom: 1px solid #2D4068; -}