Add a version string to subdoc output

danakj · danakj · commit 5b2da1a70193 · 2023-12-19T21:58:43.000-05:00
The string is specified on the command line with
--project-version.
diff --git a/.github/workflows/subdoc.yml b/.github/workflows/subdoc.yml
@@ -170,6 +170,7 @@ jobs:
             --project-logo logo.png \
             --project-md sus/project.md \
             --project-name Subspace \
+            --project-version 0.0.0 \
             --remove-source-path-prefix $PWD \
             --add-source-path-prefix ${source_url} \
             --source-path-line-prefix L \
diff --git a/.github/workflows/try.yml b/.github/workflows/try.yml
@@ -417,6 +417,7 @@ jobs:
             --project-logo logo.png \
             --project-md sus/project.md \
             --project-name Subspace \
+            --project-version 0.0.0 \
             --remove-source-path-prefix $PWD \
             --add-source-path-prefix ${source_url} \
             --source-path-line-prefix L \
diff --git a/subdoc/README.md b/subdoc/README.md
@@ -175,6 +175,12 @@ links to various parts of the project's documentation.
 Points the logo image to the given `WEB_PATH` in the generated HTML pages.
 This can be the name of a file included in the output with `--copy-file`.
 
+```
+--project-version VERSION_STRING
+```
+The version of the project, which will be displayed on the generated front
+page. If omitted, no version is shown.
+
 ```
 --favicon WEB_PATH
 ```
diff --git a/subdoc/gen_tests/function-overloads/index.html b/subdoc/gen_tests/function-overloads/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/markdown/index.html b/subdoc/gen_tests/markdown/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/nested-namespace/index.html b/subdoc/gen_tests/nested-namespace/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/struct-basic/index.html b/subdoc/gen_tests/struct-basic/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/struct-complex/index.html b/subdoc/gen_tests/struct-complex/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/templates/index.html b/subdoc/gen_tests/templates/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/gen_tests/typenames-across-paths/index.html b/subdoc/gen_tests/typenames-across-paths/index.html
@@ -39,7 +39,7 @@
       <a href="#">PROJECT NAME</a>
     </div>
     <div class="sidebar-subtitle sidebar-text">
-      TODO: version
+      Version VERSION_STRING
     </div>
     <div class="sidebar-links sidebar-text">
       <ul>
diff --git a/subdoc/lib/gen/generate_namespace.cc b/subdoc/lib/gen/generate_namespace.cc
@@ -838,12 +838,16 @@ sus::Result<void, MarkdownToHtmlError> generate_namespace(
   }
 
   auto body = html.open_body();
-  if (element.namespace_name == Namespace::Tag::Global)
-    generate_nav(body, db, "", options.project_name, "TODO: version",
+  if (element.namespace_name == Namespace::Tag::Global) {
+    std::ostringstream version;
+    if (options.version_text.is_some())
+      version << "Version " << options.version_text.as_value();
+    generate_nav(body, db, "", options.project_name, sus::move(version).str(),
                  sus::move(sidebar_links), options);
-  else
+  } else {
     generate_nav(body, db, "namespace", element.name, "",
                  sus::move(sidebar_links), options);
+  }
 
   auto main = body.open_main();
   auto namespace_div = main.open_div();
diff --git a/subdoc/lib/gen/options.h b/subdoc/lib/gen/options.h
@@ -54,6 +54,9 @@ struct FavIcon {
 struct Options {
   std::string project_name = "PROJECT NAME";
   std::string project_logo = "PROJECT LOGO.png";
+  /// The version string for the project. Typically a semver version such as
+  /// "1.2.3" or "0.2.0-beta-4".
+  sus::Option<std::string> version_text;
   // TODO: sus::PathBuf type would be real nice.
   std::filesystem::path output_root;
   sus::Vec<std::string> stylesheets;
diff --git a/subdoc/subdoc_main.cc b/subdoc/subdoc_main.cc
@@ -47,6 +47,12 @@ int main(int argc, const char** argv) {
                      "to insert into the project root"),
       llvm::cl::cat(option_category));
 
+  llvm::cl::opt<std::string> option_project_version(
+      "project-version",
+      llvm::cl::desc("A string representing the version of the project, "
+                     "such as 1.2.3"),
+      llvm::cl::cat(option_category));
+
   llvm::cl::list<std::string> option_css(
       "css",
       llvm::cl::desc(
@@ -268,6 +274,10 @@ int main(int argc, const char** argv) {
   if (option_project_logo.getNumOccurrences() > 0) {
     gen_options.project_logo = option_project_logo.getValue();
   }
+  if (option_project_version.getNumOccurrences() > 0) {
+    gen_options.version_text =
+        sus::some(sus::clone(option_project_version.getValue()));
+  }
   if (option_css.empty() && option_copy_files.empty()) {
     // Defaults to pull the test stylesheet, assuming subdoc is being run from
     // the source root directory.
diff --git a/subdoc/tests/subdoc_gen_test.h b/subdoc/tests/subdoc_gen_test.h
@@ -54,6 +54,7 @@ class SubDocGenTest : public testing::Test {
     using subdoc::gen::FavIcon;
     using namespace std::string_literals;
     auto options = subdoc::gen::Options{
+        .version_text = sus::some("VERSION_STRING"s),
         .output_root =
             [&]() {
               std::filesystem::path test_root = output_root;
diff --git a/tools/run_subdoc.bat b/tools/run_subdoc.bat
@@ -12,6 +12,7 @@ out\subdoc\subdoc -p out --out docs ^
     --project-md sus/project.md ^
     --project-logo logo.png ^
     --project-name Subspace ^
+    --project-version 0.1.2 ^
     --ignore-bad-code-links ^
     --remove-source-path-prefix %cd% ^
     --add-source-path-prefix .. ^
diff --git a/tools/run_subdoc.sh b/tools/run_subdoc.sh
@@ -14,6 +14,7 @@ out/subdoc/subdoc -p out --out docs \
     --project-md sus/project.md \
     --project-logo logo.png \
     --project-name Subspace \
+    --project-version 0.1.2 \
     --ignore-bad-code-links \
     --remove-source-path-prefix $PWD \
     --add-source-path-prefix .. \
