🐛 FIX: Docs build against non-html formats (executablebooks#88)

- Add CI tests against builders: html, latex and man
- Fix visits to fontawesome nodes, and add warning for non-supported formats

Author: chrisjsewell

.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

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('_', '-')})"
 

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