doc: update deps and build pdf (#248)

.github/workflows/build_and_publish_docs.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   build-and-deploy-docs:
@@ -25,7 +26,7 @@ jobs:
       - name: Install Dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install doxygen
+          sudo apt-get install doxygen texlive
           pip install -r doc/requirements.txt
 
       - name: Build Documentation
@@ -35,10 +36,30 @@ jobs:
           build-docs -t esp32 -l en --project-path ../ --source-dir ./ --doxyfile_dir ./ || true
           mkdir -p ../docs
           cp -r _build/en/esp32/html/* ../docs/.
+          # go to the latex output
+          cd _build/en/esp32/latex/
+          # build once
+          pdflatex -interaction=batchmode refman
+          # build again to make sure page numbers and refs and such work
+          pdflatex -interaction=batchmode refman
+          # rename refman to espp_documentation.pdf
+          mv refman.pdf espp_documentation.pdf
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs
           force_orphan: true
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: espp_documentation.pdf
+          path: doc/_build/en/esp32/latex/espp_documentation.pdf
+
+      - name: Attach files to release
+        uses: softprops/action-gh-release@v2
+        if: ${{ github.event.release && github.event.action == 'published' }}
+        with:
+          files: |
+            doc/_build/en/esp32/latex/espp_documentation.pdf

doc/Doxyfile

@@ -209,6 +209,7 @@ WARN_IF_DOC_ERROR = NO
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
+CREATE_SUBDIRS         = NO
 
 # The PREDEFINED tag can be used to specify one or more macro names that are
 # defined before the preprocessor is started (similar to the -D option of e.g.

doc/requirements.txt

@@ -3,4 +3,4 @@
 #
 cairosvg
 sphinx==4.5.0
-esp-docs==1.8.0
+esp-docs==1.10.0