Add project API version on each HTML page. (#936)

Fixes #333

Author: tristanlatr

README.rst

@@ -74,6 +74,7 @@ in development
 ^^^^^^^^^^^^^^
 
 * Allow suppressing the footer's buildtime altogether with option ``--buildtime=no``.
+* Add project version on each HTML page.
 
 pydoctor 25.10.1
 ^^^^^^^^^^^^^^^^

pydoctor/templatewriter/pages/__init__.py

@@ -272,6 +272,7 @@ def slot_map(self) -> Dict[str, "Flattenable"]:
 
         return dict(
             project=project_tag,
+            project_version=f' {system.options.projectversion}' if system.options.projectversion else '',
             pydoctor_version=__version__,
         )
 

pydoctor/test/test_templatewriter.py

@@ -674,6 +674,45 @@ def test_index_contains_infos(tmp_path: Path, theme: str) -> None:
         for i in infos:
             assert i in page, page
 
+@theme_param
+def test_project_version_shown_in_footer(tmp_path: Path, theme:str) -> None:
+    """
+    Verify that when a project name and project version are provided, the
+    generated HTML footer shows the project version.
+    """
+    system = model.System(model.Options.from_args([
+        '--project-version', '1.2.3',
+    ]))
+
+    builder = system.systemBuilder(system)
+    builder.addModule(testpackages / "allgames")
+    builder.addModule(testpackages / "basic")
+    builder.buildModules()
+
+    w = writer.TemplateWriter(tmp_path, _template_lookup(theme))
+    w.writeSummaryPages(system)
+
+    assert '1.2.3' in (tmp_path / 'index.html').read_text(encoding='utf-8')
+
+@theme_param
+def test_project_version_is_None_not_in_footer(tmp_path: Path, theme:str) -> None:
+    """
+    Verify that when a project version is NOT provided, the
+    generated HTML footer doesn't show 'None' as the version.
+    """
+    system = model.System(model.Options.from_args([]))
+
+    builder = system.systemBuilder(system)
+    builder.addModule(testpackages / "allgames")
+    builder.addModule(testpackages / "basic")
+    builder.buildModules()
+
+    w = writer.TemplateWriter(tmp_path, _template_lookup(theme))
+    w.writeSummaryPages(system)
+
+    assert 'API Documentation</a> for my project,\n' in (
+        tmp_path / 'index.html').read_text(encoding='utf-8')
+
 @pytest.mark.parametrize('_order', ["alphabetical", "source"])
 def test_objects_order_mixed_modules_and_packages(_order:str) -> None:
     """

pydoctor/themes/base/footer.html

@@ -2,7 +2,7 @@
 
   <meta name="pydoctor-template-version" content="4" />
   <div class="container-fluid">
-    <a href="index.html">API Documentation</a> for <t:slot name="project" />,
+    <a href="index.html">API Documentation</a> for <t:slot name="project" /><t:slot name="project_version" />,
   generated by <a href="https://github.com/twisted/pydoctor/">pydoctor</a>
     <t:slot name="pydoctor_version" /><t:transparent fmt=" at %Y-%m-%d %H:%M:%S" t:render="buildtime" />
   </div>

pydoctor/themes/readthedocs/footer.html

@@ -3,7 +3,7 @@
     <meta name="pydoctor-template-version" content="4" />
 
     <div class="container-fluid">
-      <a href="index.html">API Documentation</a> for <t:slot name="project" />,
+      <a href="index.html">API Documentation</a> for <t:slot name="project" /><t:slot name="project_version" />,
     generated by <a href="https://github.com/twisted/pydoctor/">pydoctor</a>
       <t:slot name="pydoctor_version" /><t:transparent fmt=" at %Y-%m-%d %H:%M:%S" t:render="buildtime" />
     </div>