Automate doxygen builds (#521)

- updated the doxyfile using doxygen -u
- include hidtest/test.c as a doc'd example
- use a brief doxygen/main_page.md file as the generated site's main page
- strip absolute paths from doxygen output (which now displays as relative paths to repo root)
- add CI to build the docs and save as a CI artifact and rewrite the contents of the gh-pages branch for deployment (for master builds)
- add some missing docstrings and excluded undocumented "helper macros" to satisfy warnings output in doxygen's build log

Author: 2bndy5

Diff for: .github/workflows/docs.yaml

@@ -13,3 +13,46 @@ jobs:
 
       - 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
+
+      - uses: actions/checkout@v3
+
+      - run: doxygen
+        working-directory: doxygen
+
+      - name: Save doxygen docs as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: HIDAPI_doxygen_docs
+          path: ${{ github.workspace }}/doxygen/html
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.ref_type == 'branch' && github.ref_name == 'master'
+    concurrency:
+      group: "github-pages-deploy"
+      cancel-in-progress: true
+    steps:
+      - name: downlod artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: HIDAPI_doxygen_docs
+          path: docs
+
+      - name: upload to github pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          force_orphan: true

Diff for: .gitignore

@@ -27,3 +27,6 @@ libtool
 
 # Qt Creator
 CMakeLists.txt.user
+
+# doxgen output
+doxygen/html/