Add support for Sphinx latexpdf output

.github/workflows/test.yml

@@ -17,14 +17,14 @@ jobs:
         python-version: ["3.8", "3.10"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: ${{ matrix.python-version }}
       - name: Setting environment
         run: |
-          mkdir /tmp/web
+          mkdir /tmp/web /tmp/pdf
           ./Sphinxsetup.sh
       - name: Check image formats
         run: |
@@ -33,6 +33,9 @@ jobs:
         run : |
           set -eux -o pipefail
           flake8 .
-      - name: Test build
+      - name: Test html build
         run: |
           ./update.py --parallel 4 --verbose --destdir=/tmp/web
+      - name: Test pdf build
+        run: |
+          ./update.py --parallel 4 --verbose --destdir=/tmp/pdf --no-html --pdf

.gitignore

@@ -24,6 +24,7 @@
 
 # Any build directory
 */build/*
+*/_build/*
 
 # Logs
 *.log

Sphinxsetup.sh

@@ -16,7 +16,7 @@ if [ ${DISTRIBUTION_ID} = 'Ubuntu' ]; then
 fi
 
 sudo apt-get -y update
-sudo apt-get install -y unzip git imagemagick curl wget make python3
+sudo apt-get install -y unzip git imagemagick curl wget make python3 texlive-latex-recommended texlive-fonts-recommended tex-gyre texlive-latex-extra latexmk fonts-freefont-otf
 
 # Install packages release specific
 if [ ${DISTRIBUTION_CODENAME} = 'bionic' ]; then
@@ -46,24 +46,12 @@ rm -f get-pip.py
 # Install sphinx with a specific docutils version
 # Docutils version is for correct bullet point rendering. Can be rolled forward after theme is updated to >=0.5.1
 # See https://stackoverflow.com/a/68685753/2578171
-python3 -m pip install --user --upgrade sphinx==5.1.1 docutils==0.16
-
-# lxml for parameter parsing:
-python3 -m pip install --user --upgrade lxml
-
+# lxml for parameter parsing
 # Install sphinx theme from ArduPilot repository
-python3 -m pip install --user --upgrade git+https://github.com/ArduPilot/sphinx_rtd_theme.git
-
-# and youtube and video plugins:
-# This command might require a --force option if you have and older extension installed
-# Rerun Sphinxsetup.sh after doing that
-python3 -m pip install --user --upgrade git+https://github.com/ArduPilot/sphinxcontrib-youtube.git
-
+# and youtube and video plugins (might require a --force option if you have an older extension installed. Rerun Sphinxsetup.sh after doing that)
 # and a parser to use getting posts from Discourse (forum) and insert in FrontEnd
-python3 -m pip install --user --upgrade beautifulsoup4
-
-# Install flake8
-python3 -m pip install --user --upgrade flake8==3.7.9
+# and flake8
+python3 -m pip install --user --upgrade "sphinx>=5" lxml git+https://github.com/ArduPilot/sphinx_rtd_theme.git git+https://github.com/ArduPilot/sphinxcontrib-youtube.git beautifulsoup4 flake8==3.7.9
 
 # Reset the value of DISPLAY
 if grep -qi -E '(Microsoft|WSL)' /proc/version; then

antennatracker/source/conf.py

@@ -223,6 +223,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -241,7 +244,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotAntennaTracker.tex', u'ArduPilot Antenna Tracker Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -251,10 +254,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

ardupilot/source/conf.py

@@ -219,6 +219,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -247,10 +250,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

blimp/source/conf.py

@@ -244,7 +244,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotBlimp.tex', u'ArduPilot Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -254,10 +254,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

common/source/docs/common-installing-3dr-ublox-gps-compass-module.rst

@@ -15,8 +15,6 @@ ArduPilot automatically configures the GPS soon after startup so there is no nee
 Connecting the Autopilot
 ========================
 
-.. _common-installing-3dr-ublox-gps-compass-module_connecting_to_pixhawk:
-
 .. image:: ../../../images/gps-connection.jpg
      :target: ../_iamges/gps-connection.jpg
 

common_conf.py

@@ -27,6 +27,9 @@
 intersphinx_base_url = wiki_base_url + '%s/'
 
 
+# Default engine is pdflatex
+latex_engine = 'pdflatex'
+
 # Where to point the base of the build for the main site menu
 html_context = {'target': '/'}
 # This needs to change to the actual URL root once the theme updated.

copter/source/conf.py

@@ -226,6 +226,8 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = common_conf.latex_engine
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -244,7 +246,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotCopter.tex', u'ArduPilot Copter Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -254,10 +256,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

dev/source/conf.py

@@ -219,6 +219,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -237,7 +240,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotDev.tex', u'ArduPilot Developer Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -247,10 +250,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

mavproxy/source/conf.py

@@ -219,6 +219,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -237,7 +240,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotMAVProxy.tex', u'ArduPilot MAVProxy Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -247,10 +250,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

plane/source/conf.py

@@ -225,6 +225,8 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = common_conf.latex_engine
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -243,7 +245,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotPlane.tex', u'ArduPilot Plane Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -253,10 +255,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

plane/source/docs/tecs-total-energy-control-system-for-speed-height-tuning-guide.rst

@@ -164,7 +164,7 @@ Flight Testing
       or the maximum sink rate :ref:`TECS_SINK_MAX<TECS_SINK_MAX>` needs to be reduced.
 
 If the height response oscillates you can try increasing the value of
-`TECS_PTCH_DAMP <#TECS_PTCH_DAMP>`__ in increments of 0.1 (don't go
+:ref:`TECS_PTCH_DAMP<TECS_PTCH_DAMP>` in increments of 0.1 (don't go
 above 0.5 unless you know how to check for excessive noise in the
 nav_pitch signal using the mission planner tuning window) and then try
 increasing the value of :ref:`TECS_TIME_CONST<TECS_TIME_CONST>` in increments of 1.0.

planner/source/conf.py

@@ -219,6 +219,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -237,7 +240,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotPlanner.tex', u'ArduPilot Planner Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -247,10 +250,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False

planner2/source/conf.py

@@ -219,6 +219,9 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
+# Default engine is pdflatex
+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     # 'papersize': 'letterpaper',
@@ -237,7 +240,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ArduPilot.tex', u'ArduPilot Documentation',
+    (master_doc, 'ArduPilotPlanner2.tex', u'ArduPilot APM Planner 2 Documentation',
      u'ArduPilot Dev Team', 'manual'),
 ]
 
@@ -247,10 +250,10 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-# latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
-# latex_show_pagerefs = False
+latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 # latex_show_urls = False