doc: stop build of docs if a locale is missing, add CMake option "ENABLE_DOC_WARN_LOCALE" (closes #1985)

5 files changed, 109 insertions, 36 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index aba92ce5e..04980dc44 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -95,39 +95,40 @@ else()
   set(INCLUDEDIR "${CMAKE_INSTALL_PREFIX}/include/${PROJECT_NAME}")
 endif()
 
-option(ENABLE_NCURSES        "Compile the Ncurses interface"            ON)
-option(ENABLE_HEADLESS       "Compile the headless binary"              ON)
-option(ENABLE_NLS            "Enable Native Language Support"           ON)
-option(ENABLE_LARGEFILE      "Enable Large File Support"                ON)
-option(ENABLE_ALIAS          "Enable Alias plugin"                      ON)
-option(ENABLE_BUFLIST        "Enable Buflist plugin"                    ON)
-option(ENABLE_CHARSET        "Enable Charset plugin"                    ON)
-option(ENABLE_EXEC           "Enable Exec plugin"                       ON)
-option(ENABLE_FIFO           "Enable FIFO plugin"                       ON)
-option(ENABLE_FSET           "Enable Fast Set plugin"                   ON)
-option(ENABLE_IRC            "Enable IRC plugin"                        ON)
-option(ENABLE_LOGGER         "Enable Logger plugin"                     ON)
-option(ENABLE_RELAY          "Enable Relay plugin"                      ON)
-option(ENABLE_SCRIPT         "Enable Script plugin (script manager)"    ON)
-option(ENABLE_SCRIPTS        "Enable script plugins (perl, python, …)"  ON)
-option(ENABLE_PERL           "Enable Perl scripting language"           ON)
-option(ENABLE_PYTHON         "Enable Python scripting language"         ON)
-option(ENABLE_RUBY           "Enable Ruby scripting language"           ON)
-option(ENABLE_LUA            "Enable Lua scripting language"            ON)
-option(ENABLE_TCL            "Enable Tcl scripting language"            ON)
-option(ENABLE_GUILE          "Enable Scheme (guile) scripting language" ON)
-option(ENABLE_JAVASCRIPT     "Enable JavaScript scripting language"     OFF)
-option(ENABLE_PHP            "Enable PHP scripting language"            ON)
-option(ENABLE_SPELL          "Enable Spell checker plugin"              ON)
-option(ENABLE_ENCHANT        "Use Enchant lib in Spell checker plugin"  OFF)
-option(ENABLE_TRIGGER        "Enable Trigger plugin"                    ON)
-option(ENABLE_TYPING         "Enable Typing plugin"                     ON)
-option(ENABLE_XFER           "Enable Xfer plugin"                       ON)
-option(ENABLE_MAN            "Enable build of man page"                 OFF)
-option(ENABLE_DOC            "Enable build of documentation"            OFF)
-option(ENABLE_DOC_INCOMPLETE "Enable incomplete doc"                    OFF)
-option(ENABLE_TESTS          "Enable tests"                             OFF)
-option(ENABLE_CODE_COVERAGE  "Enable code coverage"                     OFF)
+option(ENABLE_NCURSES         "Compile the Ncurses interface"              ON)
+option(ENABLE_HEADLESS        "Compile the headless binary"                ON)
+option(ENABLE_NLS             "Enable Native Language Support"             ON)
+option(ENABLE_LARGEFILE       "Enable Large File Support"                  ON)
+option(ENABLE_ALIAS           "Enable Alias plugin"                        ON)
+option(ENABLE_BUFLIST         "Enable Buflist plugin"                      ON)
+option(ENABLE_CHARSET         "Enable Charset plugin"                      ON)
+option(ENABLE_EXEC            "Enable Exec plugin"                         ON)
+option(ENABLE_FIFO            "Enable FIFO plugin"                         ON)
+option(ENABLE_FSET            "Enable Fast Set plugin"                     ON)
+option(ENABLE_IRC             "Enable IRC plugin"                          ON)
+option(ENABLE_LOGGER          "Enable Logger plugin"                       ON)
+option(ENABLE_RELAY           "Enable Relay plugin"                        ON)
+option(ENABLE_SCRIPT          "Enable Script plugin (script manager)"      ON)
+option(ENABLE_SCRIPTS         "Enable script plugins (perl, python, …)"    ON)
+option(ENABLE_PERL            "Enable Perl scripting language"             ON)
+option(ENABLE_PYTHON          "Enable Python scripting language"           ON)
+option(ENABLE_RUBY            "Enable Ruby scripting language"             ON)
+option(ENABLE_LUA             "Enable Lua scripting language"              ON)
+option(ENABLE_TCL             "Enable Tcl scripting language"              ON)
+option(ENABLE_GUILE           "Enable Scheme (guile) scripting language"   ON)
+option(ENABLE_JAVASCRIPT      "Enable JavaScript scripting language"       OFF)
+option(ENABLE_PHP             "Enable PHP scripting language"              ON)
+option(ENABLE_SPELL           "Enable Spell checker plugin"                ON)
+option(ENABLE_ENCHANT         "Use Enchant lib in Spell checker plugin"    OFF)
+option(ENABLE_TRIGGER         "Enable Trigger plugin"                      ON)
+option(ENABLE_TYPING          "Enable Typing plugin"                       ON)
+option(ENABLE_XFER            "Enable Xfer plugin"                         ON)
+option(ENABLE_MAN             "Enable build of man page"                   OFF)
+option(ENABLE_DOC             "Enable build of documentation"              OFF)
+option(ENABLE_DOC_INCOMPLETE  "Enable incomplete doc"                      OFF)
+option(ENABLE_DOC_WARN_LOCALE "Warning instead of error on missing locale" OFF)
+option(ENABLE_TESTS           "Enable tests"                               OFF)
+option(ENABLE_CODE_COVERAGE   "Enable code coverage"                       OFF)
 
 # code coverage
 add_library(coverage_config INTERFACE)
diff --git a/ChangeLog.adoc b/ChangeLog.adoc
index 8e8bc3270..6df77f22e 100644
--- a/ChangeLog.adoc
+++ b/ChangeLog.adoc
@@ -44,6 +44,10 @@ Bug fixes::
   * script: fix cursor position after `/script list -i` or `/script list -il`
   * script: fix buffer used by command `/script list -i|-il|-o|-ol`
 
+Build::
+
+  * doc: stop build of docs if a locale is missing, add CMake option "ENABLE_DOC_WARN_LOCALE" (issue #1985)
+
 [[v4.0.2]]
 == Version 4.0.2 (2023-07-12)
 
diff --git a/ReleaseNotes.adoc b/ReleaseNotes.adoc
index 6857704b4..c6ab051f9 100644
--- a/ReleaseNotes.adoc
+++ b/ReleaseNotes.adoc
@@ -62,6 +62,37 @@ You can reset it with this command:
 /reset weechat.key_mouse.@chat(fset.fset):button1
 ----
 
+[[v4.1.0_doc_locales]]
+=== Required locales for auto-generated docs
+
+The build of auto-generated files for docs now requires all locales to be installed. +
+If at least one locale is not installed, the following error is displayed:
+
+----
+doc generator: ERROR: failed to set locale "de_DE.UTF-8", these locales must be installed to build docs:
+  de_DE.UTF-8
+  en_US.UTF-8
+  fr_FR.UTF-8
+  it_IT.UTF-8
+  ja_JP.UTF-8
+  pl_PL.UTF-8
+  sr_RS.UTF-8
+doc generator: you can turn this error as a warning with the cmake option ENABLE_DOC_WARN_LOCALE
+----
+
+A new CMake option "ENABLE_DOC_WARN_LOCALE" has been added to allow the build
+of docs even if locales are missing:
+
+----
+cmake .. -DENABLE_DOC_WARN_LOCALE=ON
+----
+
+When this option is enabled, such warning is displayed and the doc is built anyway:
+
+----
+doc generator: WARNING: failed to set locale "de_DE.UTF-8", docs will include auto-generated English content
+----
+
 [[v4.0.2]]
 == Version 4.0.2 (2023-07-12)
 
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 35e8a2804..79c895bd3 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -180,7 +180,7 @@ if(ENABLE_MAN OR ENABLE_DOC)
         )
       endforeach()
       add_custom_target(doc-autogen ALL
-        COMMAND "${CMAKE_COMMAND}" -E env "WEECHAT_EXTRA_LIBDIR=${PROJECT_BINARY_DIR}/src" "WEECHAT_DOCGEN_LOCALEDIR=${PROJECT_BINARY_DIR}/po" "${CMAKE_BINARY_DIR}/src/gui/curses/headless/weechat-headless" --temp-dir --doc-gen "${CMAKE_CURRENT_BINARY_DIR}/autogen"
+        COMMAND "${CMAKE_COMMAND}" -E env "WEECHAT_EXTRA_LIBDIR=${PROJECT_BINARY_DIR}/src" "WEECHAT_DOCGEN_LOCALEDIR=${PROJECT_BINARY_DIR}/po" "WEECHAT_DOCGEN_WARN_LOCALE=${ENABLE_DOC_WARN_LOCALE}" "${CMAKE_BINARY_DIR}/src/gui/curses/headless/weechat-headless" --temp-dir --doc-gen "${CMAKE_CURRENT_BINARY_DIR}/autogen"
         DEPENDS
         # the headless binary is required
         weechat-headless
diff --git a/src/core/wee-doc.c b/src/core/wee-doc.c
index bfadc0a15..8014f4b72 100644
--- a/src/core/wee-doc.c
+++ b/src/core/wee-doc.c
@@ -1602,7 +1602,7 @@ doc_gen_api_config_priority (const char *path, const char *lang)
 int
 doc_generate (const char *path)
 {
-    int i, j, rc_doc_gen, rc, num_files;
+    int i, j, rc_doc_gen, rc, num_files, warn_locale;
     char *locales[] = {
         "de_DE.UTF-8",
         "en_US.UTF-8",
@@ -1662,10 +1662,47 @@ doc_generate (const char *path)
     if (localedir && localedir[0])
         bindtextdomain (PACKAGE, localedir);
 
+    /*
+     * if warn locale is enabled, any missing locale triggers a warning
+     * instead of a fatal error
+     */
+    warn_locale = (string_strcasecmp (getenv ("WEECHAT_DOCGEN_WARN_LOCALE"), "on") == 0) ?
+        1 : 0;
+
     for (i = 0; locales[i]; i++)
     {
         setenv ("LANGUAGE", locales[i], 1);
-        setlocale (LC_ALL, locales[i]);
+        if (!setlocale (LC_ALL, locales[i]))
+        {
+            if (warn_locale)
+            {
+                /* warning on missing locale */
+                string_fprintf (
+                    stderr,
+                    "doc generator: WARNING: failed to set locale \"%s\", "
+                    "docs will include auto-generated English content\n",
+                    locales[i]);
+                setlocale (LC_ALL, "C");
+            }
+            else
+            {
+                /* fatal error on missing locale */
+                string_fprintf (
+                    stderr,
+                    "doc generator: ERROR: failed to set locale \"%s\", "
+                    "these locales must be installed to build docs:\n",
+                    locales[i]);
+                for (j = 0; locales[j]; j++)
+                {
+                    string_fprintf (stderr, "  %s\n", locales[j]);
+                }
+                string_fprintf (
+                    stderr,
+                    "doc generator: you can turn this error as a warning "
+                    "with the cmake option ENABLE_DOC_WARN_LOCALE\n");
+                goto end;
+            }
+        }
         memcpy (lang, locales[i], 2);
         lang[2] = '\0';
         for (j = 0; doc_gen_functions[j]; j++)