From f309aee4d67c26e9955b324e24e6db6f167ba9f2 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Mon, 15 Aug 2022 16:39:34 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20FIX:=20Docs=20build=20against=20?=
 =?UTF-8?q?non-html=20formats=20(#88)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add CI tests against builders: html, latex and man
- Fix visits to fontawesome nodes, and add warning for non-supported formats
---
 .github/workflows/ci.yml | 20 ++++++++++++++++++++
 docs/conf.py             |  3 +++
 sphinx_design/icons.py   | 33 +++++++++++++++++++++++++++++----
 3 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 292f76a..b39148c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -77,6 +77,26 @@ jobs:
     - name: Run pytest
       run: pytest
 
+  docs-build-format:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        format: [html, latex, man]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.9"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[rtd]
+    - name: Build documentation
+      run: sphinx-build -nW --keep-going -b ${{ matrix.format }} docs/ docs/_build/${{ matrix.format }}
+
   publish:
 
     name: Publish to PyPi
diff --git a/docs/conf.py b/docs/conf.py
index cfde6e8..bf22c90 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,9 @@
 
 extensions = ["myst_parser", "sphinx_design"]
 
+suppress_warnings = ["design.fa-build"]
+sd_fontawesome_latex = True
+
 html_theme = os.environ.get("SPHINX_THEME", "alabaster")
 html_title = f"Sphinx Design ({html_theme.replace('_', '-')})"
 
diff --git a/sphinx_design/icons.py b/sphinx_design/icons.py
index 1913910..12b5cd6 100644
--- a/sphinx_design/icons.py
+++ b/sphinx_design/icons.py
@@ -7,9 +7,13 @@
 from docutils import nodes
 from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
+from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, SphinxRole
 
 from . import compiled
+from .shared import WARNING_TYPE
+
+logger = logging.getLogger(__name__)
 
 OCTICON_VERSION = "v16.1.1"
 
@@ -35,9 +39,9 @@ def setup_icons(app: Sphinx) -> None:
         fontawesome,
         html=(visit_fontawesome_html, depart_fontawesome_html),
         latex=(visit_fontawesome_latex, None),
-        text=(None, None),
-        man=(None, None),
-        texinfo=(None, None),
+        man=(visit_fontawesome_warning, None),
+        text=(visit_fontawesome_warning, None),
+        texinfo=(visit_fontawesome_warning, None),
     )
 
 
@@ -207,8 +211,29 @@ def add_fontawesome_pkg(app, config):
 
 
 def visit_fontawesome_latex(self, node):
+    """Add latex fonteawesome icon, if configured, else warn."""
     if self.config.sd_fontawesome_latex:
-        self.body.append(f"\\faicon{{{node['icon_name']}}}")
+        self.body.append(f"\\faicon{{{node['icon']}}}")
+    else:
+        logger.warning(
+            "Fontawesome icons not included in LaTeX output, "
+            f"consider 'sd_fontawesome_latex=True' [{WARNING_TYPE}.fa-build]",
+            location=node,
+            type=WARNING_TYPE,
+            subtype="fa-build",
+        )
+    raise nodes.SkipNode
+
+
+def visit_fontawesome_warning(self, node: nodes.Element) -> None:
+    """Warn that fontawesome is not supported for this builder."""
+    logger.warning(
+        "Fontawesome icons not supported for builder: "
+        f"{self.builder.name} [{WARNING_TYPE}.fa-build]",
+        location=node,
+        type=WARNING_TYPE,
+        subtype="fa-build",
+    )
     raise nodes.SkipNode