docs: make tests not build by default and improve example building

Also applied markdownlint to all markdown files (not the sphinx ones yet)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,12 +11,13 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 **Supporting Documentation**
-If your issue is CAN behavior related, it may be helpful to have a CAN trace of your issue that clearly shows the undesirable behavior. Please attach one if you think it might help, or if requested. Try to capture address claiming in addition to the bad behavior if possible. We prefer files captured with `candump -l` or `.asc` ascii format log files.  Binary Vector files `.blf` will not be accepted. 
+If your issue is CAN behavior related, it may be helpful to have a CAN trace of your issue that clearly shows the undesirable behavior. Please attach one if you think it might help, or if requested. Try to capture address claiming in addition to the bad behavior if possible. We prefer files captured with `candump -l` or `.asc` ascii format log files.  Binary Vector files `.blf` will not be accepted.
 
 **Environment (please complete the following information):**
- - OS: [e.g. Ubuntu 20.04]
- - Compiler [e.g. GCC 9.4.0]
- - CAN Driver [e.g. Socket CAN]
+
+- OS: [e.g. Ubuntu 20.04]
+- Compiler [e.g. GCC 9.4.0]
+- CAN Driver [e.g. Socket CAN]
 
 **Additional context**
 Add any other context about the problem here that you think might help us recreate or otherwise address your issue if applicable.

CMakeLists.txt

@@ -11,7 +11,8 @@ project(
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
-# Make CTest available which adds the option BUILD_TESTING
+# Make CTest available and the BUILD_TESTING option (OFF by default)
+option(BUILD_TESTING "Set to ON to enable building of tests from top level" OFF)
 include(CTest)
 if(BUILD_TESTING
    AND NOT MSVC

CONTRIBUTING.md

@@ -10,20 +10,20 @@ Our code style rules and PR reviews are based loosely on Autosar's `Guidelines f
 
 * Contributions must follow the style defined in our `.clang-format` and `.cmake-format` files. You can ensure you pass this check by running `find . -iname *.hpp -o -iname *.cpp | xargs clang-format -i` and `find . -name CMakeLists.txt | xargs cmake-format -i` at the root of the repo before submitting your PR.
 * Contributions should follow these additional style requirements, which will be checked in code reviews.
-	* Function names `snake_case`
-	* Variables `camelCase`
-	* Constant values `CAPITALIZED_SNAKE`
-	* Constants on the left in `==` and `!=` checks. Like this: `if (5 == value)` NOT `if (value == 5)`. This is to prevent accidentally omitting an `=` in the operator and creating a runtime bug.
-	* Copyright notice must be included in each file.
-	* `NULL` should not be used when `nullptr` can be used
-	* Explicit namespacing should be used for accessing namespaces outside of our namespace `isobus`, especially for the standard library `std::`
-	* No `using namespace` directives are allowed in header files
-	* Constructors with a single parameter shall be marked `explicit`
-	* Where possible, append `const` to functions that do not modify class member variables
-	* Where possible, declare variables as `constexpr` if their value can be determined at compile time
-	* Only those characters specified in the C++ Language Standard basic source character set shall be used in the source code except within the text of a wide string.
-	* In general, prefer C++ over C, though exceptions may be granted if needed
-	* This list of style items is not exhaustive, and some best practices such as include guards will also be checked in our PR reviews.
+  * Function names `snake_case`
+  * Variables `camelCase`
+  * Constant values `CAPITALIZED_SNAKE`
+  * Constants on the left in `==` and `!=` checks. Like this: `if (5 == value)` NOT `if (value == 5)`. This is to prevent accidentally omitting an `=` in the operator and creating a runtime bug.
+  * Copyright notice must be included in each file.
+  * `NULL` should not be used when `nullptr` can be used
+  * Explicit namespacing should be used for accessing namespaces outside of our namespace `isobus`, especially for the standard library `std::`
+  * No `using namespace` directives are allowed in header files
+  * Constructors with a single parameter shall be marked `explicit`
+  * Where possible, append `const` to functions that do not modify class member variables
+  * Where possible, declare variables as `constexpr` if their value can be determined at compile time
+  * Only those characters specified in the C++ Language Standard basic source character set shall be used in the source code except within the text of a wide string.
+  * In general, prefer C++ over C, though exceptions may be granted if needed
+  * This list of style items is not exhaustive, and some best practices such as include guards will also be checked in our PR reviews.
 * Doxygen should compile with no warnings when run at the root of the project with the command `doxygen doxyfile`
 * Absolutely no code shall be added that is under a more strict license than MIT or which has not had conditions met to be distributed under our license
 * Builds must pass the compilation github action
@@ -59,7 +59,7 @@ VS Code can be installed via the snap store, or by downloading it from [Microsof
 
 Clone the repo:
 
-```
+```bash
 git clone https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git
 ```
 

README.md

@@ -24,7 +24,7 @@ Check out the [tutorial website](https://isobus-plus-plus.readthedocs.io/en/late
 
 This library is compiled with CMake.
 
-```
+```bash
 cmake -S . -B build
 cmake --build build
 ```
@@ -51,15 +51,17 @@ If your target hardware is not listed above, you can easily integrate your own h
 
 There are build in examples. By default, examples are not built.
 The easiest way to build them is from the top level.
-```
+
+```bash
 cmake -S . -B build -DBUILD_EXAMPLES=ON
 cmake --build build
 ```
 
 ## Tests
 
 Tests are run with GTest. They can be invoked through ctest. Once the library is compiled, navigate to the build directory to run tests.
-```
+
+```bash
 cmake -S . -B build -DBUILD_TESTING=ON
 cmake --build build
 cd build
@@ -73,12 +75,14 @@ You can integrate this library into your own project with CMake if you want. Mul
 Make sure you have CMake and Git installed:
 
 Ubuntu:
-```
+
+```bash
 sudo apt install cmake git
 ```
 
 RHEL:
-```
+
+```bash
 sudo dnf install cmake git
 ```
 
@@ -92,14 +96,15 @@ Adding this library as a submodule to your project is one of the easier ways to
 
 Submodule the repository into your project:
 
-```
+```bash
 git submodule add https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git <destination_folder>
 git submodule update --init --recursive
 ```
+
 Then, if you're using CMake, make sure to add the submodule to your project, and link it.
 It is recommended to use the ALIAS targets exposed, which all follow the name `isobus::<target_name>`.
 
-```
+```cmake
 find_package(Threads)
 
 add_subdirectory(<path to this submodule>)
@@ -116,17 +121,17 @@ If you don't want to use Git submodules, you can also easily integrate this libr
 1. Create a folder called `cmake` in your project if you don't already have one.
 2. Inside the `cmake` folder, create a file with the following contents:
 
-```
-if(NOT TARGET isobus::Isobus)
-    include(FetchContent)
-    FetchContent_Declare(
-        AgIsoStack
-        GIT_REPOSITORY https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git
-        GIT_TAG        main
-    )
-    FetchContent_MakeAvailable(AgIsoStack)
-endif()
-```
+    ```cmake
+    if(NOT TARGET isobus::Isobus)
+        include(FetchContent)
+        FetchContent_Declare(
+            AgIsoStack
+            GIT_REPOSITORY https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git
+            GIT_TAG        main
+        )
+        FetchContent_MakeAvailable(AgIsoStack)
+    endif()
+    ```
 
 3. In your top-level CMakeLists.txt file, add `list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)` after your `project` command
 4. In your top-level CMakeLists.txt file, add `find_package(AgIsoStack MODULE)` after the above line.
@@ -140,52 +145,60 @@ We do not officially distribute this library in binary form (DLL files, for exam
 
 ### Installing The Library
 
-You can also install the library if you want.
-
-For a local install:
+You can also install the library if you want. First, from the top level directory, build AgIsoStack-plus-plus normally
 
+```bash
+cmake -S . -B build 
+cmake --build build
 ```
+
+For a local install, we set it to a known location
+
+```bash
 cmake --install build --prefix install
 ```
 
 For a system-wide install:
 
-```
+```bash
 sudo cmake --install build
 ```
 
 Then, use a call to `find_package()` to find this package.
 
 ### Use of our SAE/ISOBUS Manufacturer Code
 
-If you are integrating with our library to create an ISO11783 or J1939 application and are not selling your software or device containing that software for-profit, then you are welcome to use our manufacturer number in your application. 
+If you are integrating with our library to create an ISO11783 or J1939 application and are not selling your software or device containing that software for-profit, then you are welcome to use our manufacturer number in your application.
 
 If you are creating such an application for sale as a for-profit company, then we ask that you please obtain your own manufacturer code from SAE instead of using ours.
 
 Our manufacturer code is 1407 (decimal).
 
 ## Documentation
 
-You can view the pre-compiled doxygen here https://delgrossoengineering.com/isobus-docs
+You can view the pre-compiled doxygen here <https://delgrossoengineering.com/isobus-docs>
 
 You can also generate the doxygen documentation yourself by running the `doxygen` command inside this repo's folder.
 
 Make sure you have the prerequisites installed:
 
 Ubuntu:
-```
+
+```bash
 sudo apt install doxygen graphviz
 ```
 
 RHEL:
-```
+
+```bash
 sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
 
 sudo dnf install doxygen graphviz
 ```
 
 Then, generate the docs:
-```
+
+```bash
 doxygen doxyfile
 ```
 

examples/README.md

@@ -1,32 +1,44 @@
 # Examples
 
-The examples here can all be build from top level. 
-Another approach, more akin to how most consumers would use it, is to install the ISO11783 CAN Stack library.
-Then, use a call to `find_package()` to find this package. 
+This directory contains examples of how to use the AgIsoStack library.
 
-The same process can be used for all examples, however `diagnostic_protocol` is just shown as a reference.
+## Building all examples
 
-First, build AgIsoStack-plus-plus.
+The examples here can all be build simultaneously from the top level directory of the repository:
+
+```bash
+cmake -S . -B build -DBUILD_EXAMPLES=ON
+cmake --build build
 ```
-# Build the library like normal
-cd /path/to/root/directory/of/AgIsoStack-plus-plus
+
+## Building a single example
+
+Another approach, more akin to how most consumers would use the library, is to install the AgIsoStack first.
+And then, use a call to `find_package()` to find this installation.
+
+First, from the top level directory, build AgIsoStack-plus-plus normally
+
+```bash
 cmake -S . -B build 
 cmake --build build
-# Install it locally in a directory called "install"
-cmake --install build --prefix install
 ```
 
+We install it to a known location, here we use `install` folder relative to the root of the repository as an example.
 
-Now, build an example of your choosing.
+```bash
+cmake --install build --prefix install
 ```
-# Now, go in and build the example
+
+Now, build an example of your choosing, here we use the `diagnostic protocol` as an example, but any of the examples will work. Note that we need to tell CMake where to find the installed package, which is two directories up from the example directory. Hence, the `../../install` argument to `CMAKE_PREFIX_PATH`.
+
+```bash
 cd examples/diagnostic_protocol
-# Here, because we installed locally, you must supply the path to install
 cmake -S . -B build -DCMAKE_PREFIX_PATH=../../install
 cmake --build build
 ```
 
-Finally, run the example.
+Then, run the example. The name of the executable will be different depending on which example you built.
+
+```bash
+./build/DiagnosticProtocolExample
 ```
-./build/DiagnosticProtocolExampleTarget
-```

hardware_integration/lib/README.md

@@ -1,8 +1,8 @@
-## 3rd Party Drivers
+# 3rd Party Drivers
 
-### PEAK PCAN Basic Driver
+## PEAK PCAN Basic Driver
 
 Please read the End User License Agreement of the company PEAK-System Technik GmbH at:
-www.peak-system.com/quick/eula
+<www.peak-system.com/quick/eula>
 
 Use of the PEAK driver libraries is governed by their EULA.

sphinx/README.md

@@ -6,7 +6,7 @@ You can build the tutorial yourself if you wish.
 
 ## Install Prerequisites
 
-```
+```bash
 pip install sphinx
 pip install sphinx-rtd-theme
 ```
@@ -15,13 +15,13 @@ pip install sphinx-rtd-theme
 
 Windows:
 
-```
+```bash
 ./make html
 ```
 
 Linux:
 
-```
+```bash
 make html
 ```