From f8cc71679017519a53310362e98785956c75a598 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Sun, 1 Jan 2023 02:29:03 -0800 Subject: [PATCH 1/5] minor docs tweaks - show Table of Contents in Doxygen's Main/Related Pages - update sphinx customized CSS and conf.py - remove note about pyRF24 API --- COMMON_ISSUES.md | 2 + docs/arduino.md | 2 + docs/attiny.md | 2 + docs/atxmega.md | 2 + docs/cross_compile.md | 2 + docs/linux_install.md | 2 + docs/main_page.md | 2 + docs/mraa.md | 2 + docs/pico_sdk.md | 2 + docs/portability.md | 2 + docs/python_wrapper.md | 2 + docs/rpi_general.md | 2 + docs/sphinx/_static/custom_material.css | 67 ------------------------- docs/sphinx/conf.py | 26 ++++++++++ docs/using_cmake.md | 4 +- 15 files changed, 52 insertions(+), 69 deletions(-) diff --git a/COMMON_ISSUES.md b/COMMON_ISSUES.md index 8f455639c..6697e3c52 100644 --- a/COMMON_ISSUES.md +++ b/COMMON_ISSUES.md @@ -1,5 +1,7 @@ # Common Issues +@tableofcontents + ## Settings that must match diff --git a/docs/arduino.md b/docs/arduino.md index c0e106eee..50d6d0cfb 100644 --- a/docs/arduino.md +++ b/docs/arduino.md @@ -1,5 +1,7 @@ # Arduino +@tableofcontents + RF24 is fully compatible with Arduino boards. diff --git a/docs/attiny.md b/docs/attiny.md index 379d81b1f..20b7f0e9e 100644 --- a/docs/attiny.md +++ b/docs/attiny.md @@ -1,5 +1,7 @@ # ATTiny +@tableofcontents + ATTiny support for this library relys on the SpenceKonde ATTinyCore. Be sure to have added this core to the Arduino Boards Manager with [this install guide](http://highlowtech.org/?p=1695) See the included rf24ping85 example for pin info and usage diff --git a/docs/atxmega.md b/docs/atxmega.md index b79659072..e0a3efb65 100644 --- a/docs/atxmega.md +++ b/docs/atxmega.md @@ -1,5 +1,7 @@ # ATXMEGA +@tableofcontents + The RF24 driver can be build as a static library with Atmel Studio 7 in order to be included as any other library in another program for the XMEGA family. Currently only the [ATXMEGA D3](https://www.microchip.com/wwwproducts/en/ATxmega64d3) family is implemented. diff --git a/docs/cross_compile.md b/docs/cross_compile.md index bcff6c5fc..9d9bd59c7 100644 --- a/docs/cross_compile.md +++ b/docs/cross_compile.md @@ -1,5 +1,7 @@ # Linux cross-compilation +@tableofcontents + @warning These instructions are no longer recommended because they involve disabling security measures for the target system. Please try the [instructions using CMake](md_docs_using_cmake.html). diff --git a/docs/linux_install.md b/docs/linux_install.md index 58e2ac613..621114090 100644 --- a/docs/linux_install.md +++ b/docs/linux_install.md @@ -1,5 +1,7 @@ # Linux Installation +@tableofcontents + Generic Linux devices are supported via SPIDEV, MRAA, RPi native via BCM2835, or using LittleWire. diff --git a/docs/main_page.md b/docs/main_page.md index 5290a569d..21dc5c473 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -1,5 +1,7 @@ # Optimized High Speed Driver for nRF24L01(+) 2.4GHz Wireless Transceiver +@tableofcontents + ## Design Goals This library fork is designed to be... diff --git a/docs/mraa.md b/docs/mraa.md index 7d8f5d936..d13310287 100644 --- a/docs/mraa.md +++ b/docs/mraa.md @@ -1,5 +1,7 @@ # MRAA +@tableofcontents + MRAA is a Low Level Skeleton Library for Communication on GNU/Linux platforms. Review the [MRAA documentation](http://iotdk.intel.com/docs/master/mraa/index.html) for more information diff --git a/docs/pico_sdk.md b/docs/pico_sdk.md index f2a069905..a1f401ce7 100644 --- a/docs/pico_sdk.md +++ b/docs/pico_sdk.md @@ -1,5 +1,7 @@ # Raspberry Pi Pico SDK (for the RP2040) +@tableofcontents + Just to be very clear and concise: The following instructions are **not required to use the Arduino IDE** with any RP2040-based boards. diff --git a/docs/portability.md b/docs/portability.md index 3d92ebbaa..2fe25eba0 100644 --- a/docs/portability.md +++ b/docs/portability.md @@ -1,5 +1,7 @@ # RF24 Portability +@tableofcontents + The RF24 radio driver mainly utilizes the [Arduino API](http://arduino.cc/en/reference/homePage) for GPIO, SPI, and timing functions, which are easily replicated on various platforms. diff --git a/docs/python_wrapper.md b/docs/python_wrapper.md index d2e777d18..7bcadee74 100644 --- a/docs/python_wrapper.md +++ b/docs/python_wrapper.md @@ -1,5 +1,7 @@ # Python Wrapper +@tableofcontents + By [mz-fuzzy](https://github.com/mz-fuzzy) diff --git a/docs/rpi_general.md b/docs/rpi_general.md index 1081b2c08..cb6bde505 100644 --- a/docs/rpi_general.md +++ b/docs/rpi_general.md @@ -1,5 +1,7 @@ # Linux General/Raspberry Pi +@tableofcontents + RF24 supports a variety of Linux based devices via various drivers. Some boards like RPi can utilize multiple methods to drive the GPIO and SPI functionality. diff --git a/docs/sphinx/_static/custom_material.css b/docs/sphinx/_static/custom_material.css index 7b55bb1c1..ced617b73 100644 --- a/docs/sphinx/_static/custom_material.css +++ b/docs/sphinx/_static/custom_material.css @@ -1,53 +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); - border-left-color: hsl(301, 100%, 63%); -} - -.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); - border-left-color: hsl(0, 100%, 63%); -} - html .md-nav--primary .md-nav__title--site .md-nav__button { top: 0; left: 0; @@ -68,20 +18,3 @@ thead { .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 5b19b340f..bfdb80ee6 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -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 = "RF24 C++ library" diff --git a/docs/using_cmake.md b/docs/using_cmake.md index ce7af1c4c..20c9585e7 100644 --- a/docs/using_cmake.md +++ b/docs/using_cmake.md @@ -1,5 +1,7 @@ # Using CMake +@tableofcontents + A more modern approach instead of using hand-crafted _Makefiles_ & _configure_ scripts to build & install software. Please note that these instructions are not needed if you @@ -48,8 +50,6 @@ There is a newer automatic install script that makes use of the CMake approach. This is not the same as the traditionally provided python wrappers as the pyRF24 package can be used independent of the C++ installed libraries. For more information on this newer python package, please check out [the pyRF24 documentation](https://nrf24.github.io/pyRF24/). - Note, the pyRF24 API is more pythonic instead of a direct port of the C++ API (eg. snake casing - instead of camel casing). 4. Try an example from one of the libraries ```shell cd ~/rf24libs/RF24/examples_linux From a5d746a696c8174a279a8ba9684729dce9b39325 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Fri, 30 Dec 2022 21:06:36 -0800 Subject: [PATCH 2/5] update docs CI use latest doxygen release update set-output cmd in docs CI update action versions in docs CI --- .github/workflows/doxygen.yml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index d02e3b12e..26d987939 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -40,20 +40,20 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: get latest release version number id: latest_ver - run: echo "::set-output name=release::$(awk -F "=" '/version/ {print $2}' library.properties)" + run: echo "release=$(awk -F "=" '/version/ {print $2}' library.properties)" >> $GITHUB_OUTPUT - 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 + run: sudo apt-get install libclang1-12 libclang-cpp12 - name: install doxygen from SF binary archives env: - DOXYGEN_VERSION: '1.9.4' + DOXYGEN_VERSION: '1.9.6' 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 @@ -63,7 +63,7 @@ jobs: sudo make install - run: doxygen - name: Save doxygen docs as artifact - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v3 with: name: "RF24_doxygen_docs" path: ${{ github.workspace }}/docs/html @@ -75,14 +75,16 @@ jobs: publish_dir: ./docs/html # build pretty docs using doxygen XML output with Sphinx - - uses: actions/setup-python@v2 + - uses: actions/setup-python@v4 + with: + python-version: 3.x - 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 + uses: actions/upload-artifact@v3 with: name: "RF24_sphinx_docs" path: ${{ github.workspace }}/docs/_build From 3f58d04caa8d157fc3ba0264572be915d6944c67 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Fri, 30 Dec 2022 21:28:39 -0800 Subject: [PATCH 3/5] update doxygen config (requires v1.9.5+) --- Doxyfile | 25 +- doxygen-custom.css | 815 --------------------------------------------- 2 files changed, 15 insertions(+), 825 deletions(-) delete mode 100644 doxygen-custom.css diff --git a/Doxyfile b/Doxyfile index 216e7bee0..f04f99bf8 100644 --- a/Doxyfile +++ b/Doxyfile @@ -291,18 +291,23 @@ SOURCE_BROWSER = YES # Configuration options related to the HTML output #--------------------------------------------------------------------------- -# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined -# cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. -# This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefore more robust against future updates. -# Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra style sheet files is of importance (e.g. the last -# style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. +# 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_EXTRA_STYLESHEET = doxygen-custom.css +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 diff --git a/doxygen-custom.css b/doxygen-custom.css deleted file mode 100644 index 236f3e3b9..000000000 --- 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; -} From 43003d9dfcf2c081b6294839271fbc6abbd9a40b Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Wed, 4 Jan 2023 01:15:39 -0800 Subject: [PATCH 4/5] move docs-related files into docs folder - revert some Doxygen CSS changes - update RTD build Update paths Update Doxyfile One more modification update all CI also amend readme instructions fix RTD build and some CI changes fix doxyfile config value keep doxygen output relative to root self review changes restore dynamic version number in Doxyfile --- .github/workflows/build_arduino.yml | 10 +++--- .github/workflows/build_linux.yml | 18 ++++++----- .github/workflows/build_platformIO.yml | 18 ++++++----- .github/workflows/build_rp2xxx.yml | 12 +++++--- .github/workflows/doxygen.yml | 6 ++-- Doxyfile => docs/Doxyfile | 41 +++++++++++++++++++------ docs/README.md | 37 +++++++++++++++++++++- docs/doxygen-custom.css | 3 ++ docs/sphinx/README.md | 2 ++ docs/sphinx/_static/custom_material.css | 4 +-- docs/sphinx/conf.py | 2 +- 11 files changed, 112 insertions(+), 41 deletions(-) rename Doxyfile => docs/Doxyfile (90%) create mode 100644 docs/doxygen-custom.css diff --git a/.github/workflows/build_arduino.yml b/.github/workflows/build_arduino.yml index 9b1ca67e1..4801ffe2c 100644 --- a/.github/workflows/build_arduino.yml +++ b/.github/workflows/build_arduino.yml @@ -23,7 +23,9 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 # - name: Install clang-tools # uses: KyleMayes/install-llvm-action@v1 @@ -111,7 +113,7 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Compile examples uses: arduino/compile-sketches@main @@ -197,7 +199,7 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Compile examples uses: arduino/compile-sketches@main @@ -216,7 +218,7 @@ jobs: # 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 + uses: actions/upload-artifact@v3 with: name: ${{ env.SKETCHES_REPORTS }} path: ${{ env.SKETCHES_REPORTS }} diff --git a/.github/workflows/build_linux.yml b/.github/workflows/build_linux.yml index 689dbea0c..f1b61d94b 100644 --- a/.github/workflows/build_linux.yml +++ b/.github/workflows/build_linux.yml @@ -58,7 +58,9 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x # Ubuntu 20.04.4 LTS reunners ship with clang-tools v12 # - name: Install clang-tools # uses: KyleMayes/install-llvm-action@v1 @@ -100,7 +102,7 @@ jobs: CFLAGS: "-I /usr/local/include" steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: provide toolchain run: | @@ -217,7 +219,7 @@ jobs: steps: - name: Checkout RF24 repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 # - name: provide toolchain (for x86_64) # if: ${{ matrix.toolchain.compiler == 'x86_64' }} @@ -310,7 +312,7 @@ jobs: run: sudo cpack - name: Save artifact - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v3 with: name: "pkg_RF24" path: | @@ -319,10 +321,10 @@ jobs: - name: Upload Release assets if: github.event_name == 'release' && (matrix.toolchain.compiler == 'armhf' || matrix.toolchain.compiler == 'arm64') && (matrix.driver =='RPi' || matrix.driver =='SPIDEV') - uses: csexton/release-asset-action@master + uses: shogo82148/actions-upload-release-asset@v1 with: - pattern: "${{ github.workspace }}/build/pkgs/librf24*" - github-token: ${{ secrets.GITHUB_TOKEN }} + upload_url: ${{ github.event.release.upload_url }} + asset_path: "${{ github.workspace }}/build/pkgs/librf24*" - name: clean build environment working-directory: ${{ github.workspace }}/build @@ -346,7 +348,7 @@ jobs: # 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 + uses: actions/setup-python@v4 with: python-version: 3.7 diff --git a/.github/workflows/build_platformIO.yml b/.github/workflows/build_platformIO.yml index b5f2e2a8a..b8889b8d6 100644 --- a/.github/workflows/build_platformIO.yml +++ b/.github/workflows/build_platformIO.yml @@ -28,7 +28,7 @@ jobs: - name: get latest release version number id: latest_ver - run: echo "::set-output name=release::$(awk -F "=" '/version/ {print $2}' library.properties)" + run: echo "release=$(awk -F "=" '/version/ {print $2}' library.properties)" >> $GITHUB_OUTPUT - name: Set up Python uses: actions/setup-python@v2 @@ -49,10 +49,10 @@ jobs: - name: Upload Release assets if: github.event_name == 'release' - uses: csexton/release-asset-action@master + uses: shogo82148/actions-upload-release-asset@v1 with: - pattern: "PlatformIO*.tar.gz" - github-token: ${{ secrets.GITHUB_TOKEN }} + upload_url: ${{ github.event.release.upload_url }} + asset_path: "PlatformIO*.tar.gz" - name: upload package to PlatformIO Registry if: github.event_name == 'release' && github.event_type != 'created' @@ -118,21 +118,23 @@ jobs: - "adafruit_qtpy_esp32s2" steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Cache pip - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ runner.os }}-pip- - name: Cache PlatformIO - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: ~/.platformio key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 + with: + python-version: 3.x - name: Install PlatformIO run: | python -m pip install --upgrade pip diff --git a/.github/workflows/build_rp2xxx.yml b/.github/workflows/build_rp2xxx.yml index 6135c01f8..078061ced 100644 --- a/.github/workflows/build_rp2xxx.yml +++ b/.github/workflows/build_rp2xxx.yml @@ -34,14 +34,16 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x # 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 + run: python3 -m pip install cpp-linter - name: run linter as a python package id: linter run: | @@ -80,13 +82,13 @@ jobs: steps: - name: checkout RF24 lib - uses: actions/checkout@v2 + uses: actions/checkout@v3 - 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 + uses: actions/checkout@v3 with: repository: raspberrypi/pico-sdk # master branch is latest stable release @@ -115,7 +117,7 @@ jobs: run: cmake --build . --config $BUILD_TYPE - name: Save artifact - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v3 with: name: examples_pico_${{ matrix.board }} path: | diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 26d987939..4753365fe 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -45,6 +45,7 @@ jobs: id: latest_ver run: echo "release=$(awk -F "=" '/version/ {print $2}' library.properties)" >> $GITHUB_OUTPUT - name: overwrite doxygen tags + working-directory: docs run: | touch doxygenAction echo "PROJECT_NUMBER = ${{ steps.latest_ver.outputs.release }}" >> doxygenAction @@ -61,7 +62,7 @@ jobs: tar xf doxygen.tar cd doxygen-$DOXYGEN_VERSION sudo make install - - run: doxygen + - run: cd docs && doxygen - name: Save doxygen docs as artifact uses: actions/upload-artifact@v3 with: @@ -81,8 +82,7 @@ jobs: - 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 + run: sphinx-build docs/sphinx docs/_build - name: Save sphinx docs as artifact uses: actions/upload-artifact@v3 with: diff --git a/Doxyfile b/docs/Doxyfile similarity index 90% rename from Doxyfile rename to docs/Doxyfile index f04f99bf8..6c1fd1edb 100644 --- a/Doxyfile +++ b/docs/Doxyfile @@ -34,7 +34,17 @@ PROJECT_BRIEF = "TMRh20 2020 - Optimized fork of the nRF24L01+ driver" # 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 = ../ # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given @@ -143,9 +153,9 @@ WARN_AS_ERROR = YES # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ./ \ - ./utility/Template \ - ./docs +INPUT = ../ \ + ../utility/Template \ + ./ # 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 @@ -244,8 +254,8 @@ EXCLUDE_SYMBOLS = _ # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = examples \ - examples_linux +EXAMPLE_PATH = ../examples \ + ../examples_linux # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -265,14 +275,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 @@ -291,6 +301,19 @@ SOURCE_BROWSER = YES # Configuration options related to the HTML output #--------------------------------------------------------------------------- +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to 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. # @@ -376,4 +399,4 @@ XML_OUTPUT = sphinx/xml # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = DOXYGEN_FORCED +PREDEFINED = DOXYGEN_FORCED \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 4de76d0c6..763aa4b40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,39 @@ # Please browse the docs from either http://nrf24.github.io/RF24 or https://rf24.rtfd.io + ## Intended for use in Doxygen -These markdown files (\*.md) in this docs folder contain relative hyperlinks. Any relative hyperlinks will not work when viewing these markdown files in github. +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 000000000..7d56191d7 --- /dev/null +++ b/docs/doxygen-custom.css @@ -0,0 +1,3 @@ +table.markdownTable th { + color: unset; +} diff --git a/docs/sphinx/README.md b/docs/sphinx/README.md index 5ca5047f1..529ccc384 100644 --- a/docs/sphinx/README.md +++ b/docs/sphinx/README.md @@ -1,3 +1,5 @@ # Intended for Sphinx only The files in this folder are only used to generate documentation using Sphinx (from Doxygen's XML output). + +See building docs instructions in docs/README.md diff --git a/docs/sphinx/_static/custom_material.css b/docs/sphinx/_static/custom_material.css index ced617b73..dd7e9fe2f 100644 --- a/docs/sphinx/_static/custom_material.css +++ b/docs/sphinx/_static/custom_material.css @@ -6,8 +6,8 @@ html .md-nav--primary .md-nav__title--site .md-nav__button { } thead { - background-color: var(--md-default-fg-color--light); - color: var(--md-primary-bg-color); + 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 { diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index bfdb80ee6..c9aa50c45 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -81,7 +81,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 ------------------------------------------------- From cea7e2ec960db03c08393314fc26d8aeb49d5c82 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Sun, 8 Jan 2023 13:02:18 -0800 Subject: [PATCH 5/5] make all CI reusable workflow callers --- .github/workflows/build_arduino.yml | 170 ++++++--------------- .github/workflows/build_linux.yml | 200 ++----------------------- .github/workflows/build_platformIO.yml | 105 ++----------- .github/workflows/build_rp2xxx.yml | 86 +---------- .github/workflows/doxygen.yml | 57 +------ docs/Doxyfile | 2 +- 6 files changed, 84 insertions(+), 536 deletions(-) diff --git a/.github/workflows/build_arduino.yml b/.github/workflows/build_arduino.yml index 4801ffe2c..066826325 100644 --- a/.github/workflows/build_arduino.yml +++ b/.github/workflows/build_arduino.yml @@ -13,46 +13,50 @@ on: - ".github/workflows/build_arduino.yml" - "examples/**" - "!examples/old_backups/**" -env: - # convenient variable used multiple times - SKETCHES_REPORTS: sketches-reports jobs: check_formatting: - runs-on: ubuntu-latest + uses: nRF24/.github/.github/workflows/cpp_lint.yaml@main + with: + ignore: examples/old_backups + extensions: ino - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - # 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 cpp-linter - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --extensions=ino \ - --ignore='examples/old_backups' - - name: Linter checks failed? - if: steps.linter.outputs.checks-failed > 0 - run: exit 1 build: needs: check_formatting - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_arduino.yaml@main + with: + sketch-paths: | + - examples/GettingStarted + - examples/AcknowledgementPayloads + - examples/ManualAcknowledgements + - examples/StreamingData + - examples/MulticeiverDemo + - examples/InterruptConfigure + - examples/scanner + - examples/encodeRadioDetails + # The following examples still exist for posterity. They don't trigger this workflow + # - examples/old_backups/GettingStarted_HandlingFailures + # - examples/old_backups/pingpair_dyn + # - examples/old_backups/pingpair_irq + # - examples/old_backups/pingpair_multi_dyn + # - examples/old_backups/pingpair_sleepy + # - examples/old_backups/TransferTimeouts + # - examples/old_backups/recipes/led_remote + # - examples/old_backups/recipes/nordic_fob + # - examples/old_backups/recipes/pingpair_maple + fqbn: ${{ matrix.fqbn }} + enable-deltas-report: ${{ matrix.enable-deltas-report }} + # install earlphilhower's arduino-pico platform index + platforms: | + - name: rp2040:rp2040 + source-url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json + - name: arduino:avr + - name: arduino:megaavr + - name: arduino:sam + - name: arduino:samd + - name: arduino:mbed strategy: fail-fast: false - matrix: fqbn: - "arduino:avr:yun" @@ -101,7 +105,7 @@ jobs: # - "arduino:megaavr:nano4809" # board not found - "arduino:sam:arduino_due_x_dbg" # By default, don't generate size deltas data. - enable-deltas-report: + enable-deltas-report: - false # Generate size deltas data for this board include: @@ -109,62 +113,22 @@ jobs: enable-deltas-report: true - fqbn: arduino:samd:mkrzero # InterruptConfigure.ino uses pin 2 enable-deltas-report: true - - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Compile examples - uses: arduino/compile-sketches@main - with: - sketch-paths: | - - examples/GettingStarted - - examples/AcknowledgementPayloads - - examples/ManualAcknowledgements - - examples/StreamingData - - examples/MulticeiverDemo - - examples/InterruptConfigure - - examples/scanner - - examples/encodeRadioDetails - # The following examples still exist for posterity. They don't trigger this workflow - # - examples/old_backups/GettingStarted_HandlingFailures - # - examples/old_backups/pingpair_dyn - # - examples/old_backups/pingpair_irq - # - examples/old_backups/pingpair_multi_dyn - # - examples/old_backups/pingpair_sleepy - # - examples/old_backups/TransferTimeouts - # - examples/old_backups/recipes/led_remote - # - examples/old_backups/recipes/nordic_fob - # - examples/old_backups/recipes/pingpair_maple - fqbn: ${{ matrix.fqbn }} - enable-deltas-report: ${{ matrix.enable-deltas-report }} - sketches-report-path: ${{ env.SKETCHES_REPORTS }} - # install earlphilhower's arduino-pico platform index - platforms: | - - name: rp2040:rp2040 - source-url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json - - name: arduino:avr - - name: arduino:megaavr - - name: arduino:sam - - name: arduino:samd - - name: arduino:mbed - - # 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 }} attiny: needs: check_formatting - runs-on: ubuntu-latest - + uses: nRF24/.github/.github/workflows/build_arduino.yaml@main + with: + platforms: | + - source-url: "http://drazzy.com/package_drazzy.com_index.json" + name: "ATTinyCore:avr" + - name: "arduino:avr" + sketch-paths: | + - examples/rf24_ATTiny/rf24ping85 + - examples/rf24_ATTiny/timingSearch3pin + fqbn: ${{ matrix.fqbn }} + enable-deltas-report: ${{ matrix.enable-deltas-report }} strategy: fail-fast: false - matrix: fqbn: - ATTinyCore:avr:attinyx4 @@ -197,44 +161,8 @@ jobs: - fqbn: ATTinyCore:avr:attinyx5 enable-deltas-report: true - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Compile examples - uses: arduino/compile-sketches@main - with: - platforms: | - - source-url: "http://drazzy.com/package_drazzy.com_index.json" - name: "ATTinyCore:avr" - - name: "arduino:avr" - sketch-paths: | - - examples/rf24_ATTiny/rf24ping85 - - examples/rf24_ATTiny/timingSearch3pin - 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@v3 - 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, attiny] 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 f1b61d94b..205f7fdde 100644 --- a/.github/workflows/build_linux.yml +++ b/.github/workflows/build_linux.yml @@ -54,32 +54,9 @@ env: jobs: check_formatting: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - # 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 cpp-linter - - 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|utility/RPi/bcm2835.h|utility/RPi/bcm2835.c' - - 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|utility/RPi/bcm2835.h|utility/RPi/bcm2835.c' ####################### using Makefile ############################# build: @@ -174,14 +151,17 @@ jobs: ####################### using CMake ################################ using_cmake: needs: check_formatting - runs-on: ubuntu-latest - - env: - RF24_DRIVER: ${{ matrix.driver }} - + uses: nRF24/.github/.github/workflows/build_linux_cmake.yaml@main + with: + rf24-ref: ${{ github.sha }} + driver: ${{ matrix.driver }} + compiler: ${{ matrix.toolchain.compiler }} + usr-dir: ${{ matrix.toolchain.usr_dir }} + examples-path: examples_linux + deploy-release: ${{ github.event_name == 'release' && (matrix.toolchain.compiler == 'armhf' || matrix.toolchain.compiler == 'arm64') && (matrix.driver =='RPi' || matrix.driver =='SPIDEV') }} + py-wrapper-path: pyRF24 strategy: fail-fast: false - matrix: toolchain: - compiler: "armhf" @@ -216,159 +196,3 @@ jobs: toolchain: compiler: "default" # github runner is hosted on a "amd64" usr_dir: "local" - - steps: - - name: Checkout RF24 repo - uses: actions/checkout@v3 - - # - 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: provide MRAA - if: ${{ matrix.driver == 'MRAA' }} - run: | - git clone https://github.com/intel-iot-devkit/mraa.git - cd mraa - mkdir build - cd build - cmake .. -D BUILDSWIGNODE=OFF \ - -D CMAKE_INSTALL_PREFIX=/usr/${{ matrix.toolchain.usr_dir }} \ - -D CMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - sudo make install - - - name: provide WiringPi - if: ${{ matrix.driver == 'wiringPi' && matrix.toolchain.compiler == 'default' }} - run: | - git clone https://github.com/WiringPi/WiringPi - cd WiringPi - ./build - - # - name: provide WiringPi (with toolchain compilers) - # if: ${{ matrix.driver == 'wiringPi' && matrix.toolchain.compiler != 'default' }} - # env: - # CC: /usr/bin/${{ matrix.toolchain.usr_dir }}-gcc - # CFLAGS: "-I/usr/${{ matrix.toolchain.usr_dir }}" - # run: | - # git clone https://github.com/WiringPi/WiringPi - # cd WiringPi - # ./build - - - name: provide pigpio - if: matrix.driver == 'pigpio' - run: | - git clone https://github.com/joan2937/pigpio.git - cd pigpio - git fetch --tags - latestTag=$(git describe --tags `git rev-list --tags --max-count=1`) - git checkout $latestTag - mkdir build - cd build - cmake .. -D CMAKE_INSTALL_PREFIX=/usr/${{ matrix.toolchain.usr_dir }} \ - -D CMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - make - sudo make install - - - 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@v3 - with: - name: "pkg_RF24" - 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') && (matrix.driver =='RPi' || matrix.driver =='SPIDEV') - uses: shogo82148/actions-upload-release-asset@v1 - with: - upload_url: ${{ github.event.release.upload_url }} - asset_path: "${{ github.workspace }}/build/pkgs/librf24*" - - - name: clean build environment - working-directory: ${{ github.workspace }}/build - run: sudo rm -r ./* - - - name: configure examples - working-directory: ${{ github.workspace }}/build - # interruptConfigure isn't compatible with RF24 lib's support of MRAA as a driver - # interruptConfigure uses `attachInterrupt()` instead of wiringPi's `waitFor/interrupt()` - # executables linked to wiringPi additionally need to be linked to crypt and shm_open - run: | - cmake ../examples_linux \ - -D CMAKE_TOOLCHAIN_FILE=../cmake/toolchains/${{ matrix.toolchain.compiler }}.cmake - - - name: build examples - working-directory: ${{ github.workspace }}/build - run: | - cmake --build . - file ./gettingstarted - - # 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@v4 - 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-pip - python3 -m pip install --upgrade pip 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 }}/pyRF24 - run: python3 setup.py build - - - name: install python wrapper - if: ${{ matrix.toolchain.compiler == 'default' }} - working-directory: ${{ github.workspace }}/pyRF24 - run: sudo python3 setup.py install diff --git a/.github/workflows/build_platformIO.yml b/.github/workflows/build_platformIO.yml index b8889b8d6..afe9f31b8 100644 --- a/.github/workflows/build_platformIO.yml +++ b/.github/workflows/build_platformIO.yml @@ -21,81 +21,23 @@ 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 "release=$(awk -F "=" '/version/ {print $2}' library.properties)" >> $GITHUB_OUTPUT - - - 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-RF24-${{ steps.latest_ver.outputs.release }}.tar.gz - - - name: Save artifact - uses: actions/upload-artifact@v2 - with: - name: "PIO_pkg_RF24" - path: PlatformIO*.tar.gz - - - name: Upload Release assets - if: github.event_name == 'release' - uses: shogo82148/actions-upload-release-asset@v1 - with: - upload_url: ${{ github.event.release.upload_url }} - asset_path: "PlatformIO*.tar.gz" - - - name: upload package to PlatformIO Registry - if: github.event_name == 'release' && github.event_type != 'created' - # 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 cpp-linter - - name: run linter as a python package - id: linter - run: | - cpp-linter \ - --version=12 \ - --style=file \ - --tidy-checks='-*' \ - --files-changed-only='False' \ - --extensions=ino \ - --ignore='examples/old_backups' - - 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/old_backups + 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/GettingStarted/GettingStarted.ino" @@ -116,30 +58,3 @@ jobs: - "blackpill_f103c8" - "nodemcuv2" - "adafruit_qtpy_esp32s2" - - steps: - - uses: actions/checkout@v3 - - name: Cache pip - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - - name: Cache PlatformIO - uses: actions/cache@v3 - with: - path: ~/.platformio - key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }} - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: 3.x - - name: Install PlatformIO - run: | - python -m pip install --upgrade pip - pip install --upgrade platformio - - 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 078061ced..063dc2a5a 100644 --- a/.github/workflows/build_rp2xxx.yml +++ b/.github/workflows/build_rp2xxx.yml @@ -24,46 +24,20 @@ on: - "utility/rp2/*" - "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@v4 - with: - python-version: 3.x - # 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 cpp-linter - - 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 }} + rf24-ref: ${{ github.sha }} strategy: fail-fast: false - matrix: board: - "pico" @@ -79,49 +53,3 @@ jobs: - "pimoroni_picolipo_4mb" # requires PicoSDK v1.2.0 - "pimoroni_picolipo_16mb" # requires PicoSDK v1.2.0 - "pimoroni_pga2040" # requires PicoSDK v1.2.0 - - steps: - - name: checkout RF24 lib - uses: actions/checkout@v3 - - - 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@v3 - 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 - env: - PICO_SDK_PATH: ${{ github.workspace }}/pico-sdk - run: cmake -E make_directory ${{ github.workspace }}/build - - - name: Configure CMake - working-directory: ${{ github.workspace }}/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 }}/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@v3 - with: - name: examples_pico_${{ matrix.board }} - path: | - ${{ github.workspace }}/build/*.uf2 - ${{ github.workspace }}/build/*.elf - # ${{ github.workspace }}/build/*.hex - # ${{ github.workspace }}/build/*.bin diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 4753365fe..980b6b205 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -36,55 +36,8 @@ on: workflow_dispatch: jobs: - build-doxygen: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - name: get latest release version number - id: latest_ver - run: echo "release=$(awk -F "=" '/version/ {print $2}' library.properties)" >> $GITHUB_OUTPUT - - name: overwrite doxygen tags - working-directory: docs - 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-12 libclang-cpp12 - - name: install doxygen from SF binary archives - env: - DOXYGEN_VERSION: '1.9.6' - 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: cd docs && doxygen - - name: Save doxygen docs as artifact - uses: actions/upload-artifact@v3 - with: - name: "RF24_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@v4 - with: - python-version: 3.x - - name: Install sphinx deps - run: python -m pip install -r docs/sphinx/requirements.txt - - name: build docs with Sphinx - run: sphinx-build docs/sphinx docs/_build - - name: Save sphinx docs as artifact - uses: actions/upload-artifact@v3 - with: - name: "RF24_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/docs/Doxyfile b/docs/Doxyfile index 6c1fd1edb..d5015a11d 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -399,4 +399,4 @@ XML_OUTPUT = sphinx/xml # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = DOXYGEN_FORCED \ No newline at end of file +PREDEFINED = DOXYGEN_FORCED