Merge branch 'main' of github.com:python-project-templates/yardang

Author: timkpaine

docs/src/configuration.md

@@ -282,7 +282,7 @@ yardang preview
 ```
 
 This renders the documentation into `docs/html/_previews/<theme>/` for each
-bundled theme (`furo`, `sphinxawesome_theme`, `shibuya`, `fuma`). Themes whose
+bundled theme (`furo`, `sphinxawesome_theme`, `shibuya`, `fuma`, `klink`). Themes whose
 package is not installed are skipped. Restrict the set with `--themes`:
 
 ```bash
@@ -303,6 +303,7 @@ each theme is browsable live at a suburl of the published site:
 - [`/_previews/sphinxawesome_theme/`](https://yardang.python-templates.dev/_previews/sphinxawesome_theme/)
 - [`/_previews/shibuya/`](https://yardang.python-templates.dev/_previews/shibuya/)
 - [`/_previews/fuma/`](https://yardang.python-templates.dev/_previews/fuma/)
+- [`/_previews/klink/`](https://yardang.python-templates.dev/_previews/klink/)
 
 ## `source-dir`
 

docs/src/home.md

@@ -6,7 +6,7 @@
 </div>
 
 [![GitHub](https://img.shields.io/badge/repo-github-181717?logo=github&logoColor=white)](https://github.com/python-project-templates/yardang)
-[![Build Status](https://github.com/python-project-templates/yardang/actions/workflows/build.yml/badge.svg?branch=main&event=push)](https://github.com/python-project-templates/yardang/actions/workflows/build.yml)
+[![Build Status](https://github.com/python-project-templates/yardang/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/python-project-templates/yardang/actions/workflows/build.yaml)
 [![codecov](https://codecov.io/gh/python-project-templates/yardang/branch/main/graph/badge.svg)](https://codecov.io/gh/python-project-templates/yardang)
 [![License](https://img.shields.io/github/license/python-project-templates/yardang)](https://github.com/python-project-templates/yardang)
 [![PyPI](https://img.shields.io/pypi/v/yardang.svg)](https://pypi.python.org/pypi/yardang)

yardang/conf.py.j2

@@ -34,7 +34,9 @@ copyright = """{{copyright}}"""
 title = """{{title}}"""
 version = "{{version}}"
 release = "{{version}}"
-html_title = """{{title}} <code style='font-size: var(--font-size--small--4);color: var(--sd-color-primary);'>v{{version}}</code>"""
+# Sphinx reuses this as the <title> tag, so it has to stay plain text; markup
+# here shows up escaped in browser tabs and search results.
+html_title = """{{title}} v{{version}}"""
 docs_host_root = "{{docs_root}}"
 root = "{{root}}"
 cname = "{{ cname or '' }}"
@@ -133,8 +135,11 @@ html_theme = "{{theme}}"
 if html_theme == "klink":
     import klink
     html_theme_path = [klink.get_html_theme_path()]
-    html_title = f"{title} v{version}"
 html_theme_options = {{html_theme_options}}
+# klink's theme.conf points at _static/logo.png by default, which yardang does
+# not ship, so drop it unless a logo was configured explicitly.
+if html_theme == "klink":
+    html_theme_options.setdefault("logo", "")
 html_static_path = {{html_static_path}}
 html_extra_path = {{html_extra_path}}
 html_css_files = [
@@ -414,6 +419,14 @@ def run_convert_github_admonitions_to_rst(app, filename, lines):
         lines[i] = "\n".join(orig_line_splits)
 
 
+def run_title_fallback(app, pagename, templatename, context, doctree):
+    # Sphinx only takes a document title when the page opens with a single top
+    # level section, so a README that leads with a logo or badges leaves the
+    # root page reading "<no title>".
+    if context.get("title") in (None, "", "&lt;no title&gt;", "<no title>"):
+        context["title"] = title
+
+
 def setup(app):
     if {{previous_versions}}:
         app.connect("builder-inited", run_create_previous_version_markdown)
@@ -423,3 +436,4 @@ def setup(app):
     {% endif %}
     app.connect("builder-inited", run_copycname)
     app.connect("source-read", run_convert_github_admonitions_to_rst)
+    app.connect("html-page-context", run_title_fallback)

yardang/tests/test_themes.py

@@ -32,6 +32,15 @@ def test_other_themes_are_unchanged(self):
         assert build_module.theme_module("furo") == "furo"
 
 
+class TestDocumentedThemes:
+    """The theme lists in the docs are maintained by hand, so they drift."""
+
+    @pytest.mark.parametrize("theme", BUNDLED_THEMES)
+    def test_theme_has_a_preview_link(self, theme):
+        docs = Path(__file__).parents[2] / "docs" / "src" / "configuration.md"
+        assert f"/_previews/{theme}/" in docs.read_text()
+
+
 class TestSearchIntegration:
     """Search is theme-independent, so it is wired for every first-class theme."""
 
@@ -46,7 +55,7 @@ def _conf(self, tmp_path, **kwargs):
         finally:
             os.chdir(original_cwd)
 
-    @pytest.mark.parametrize("theme", ["furo", "shibuya", "sphinxawesome_theme", "fuma"])
+    @pytest.mark.parametrize("theme", BUNDLED_THEMES)
     def test_searchlite_is_enabled_for_first_class_themes(self, tmp_path, theme):
         assert "sphinx_searchlite" in self._conf(tmp_path, theme=theme)