Merge topic 'ci-cmake.org-help' into release-3.23

2808281730 gitlab-ci: update cmake.org documentation in release package pipeline
ed00a29cce gitlab-ci: consolidate jobs for cmake.org/cmake/help/git-{master,stage} docs
5c2e8ce515 Utilities/Sphinx: Add OpenSearch link to html page headers on cmake.org
a14905d4df Utilities/Sphinx: Add option to build outdated version banner for cmake.org
cca73b54ae Utilities/Sphinx: Add undocumented option to build docs for cmake.org

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7144

7 files changed, 109 insertions, 36 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d8c16aec27..1b1ddbe5c7 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -70,37 +70,21 @@ u:source-package:
 
 # Documentation builds
 
-b:help:master:
+b:cmake.org-help:
     extends:
         - .cmake_org_help
-        - .run_only_for_continuous_master
+        - .run_cmake_org_help
+    dependencies: []
+    needs: []
 
-.u:help:master:
+u:cmake.org-help:
     extends:
         - .rsync_upload_help
-        - .run_only_for_continuous_master
-    variables:
-        RSYNC_DESTINATION: git-master
-    dependencies:
-        - b:help:master
-    needs:
-        - b:help:master
-
-b:help:stage:
-    extends:
-        - .cmake_org_help
-        - .run_only_for_continuous_stage
-
-.u:help:stage:
-    extends:
-        - .rsync_upload_help
-        - .run_only_for_continuous_stage
-    variables:
-        RSYNC_DESTINATION: git-stage
+        - .run_cmake_org_help
     dependencies:
-        - b:help:stage
+        - b:cmake.org-help
     needs:
-        - b:help:stage
+        - b:cmake.org-help
 
 # Lint builds
 
diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml
index ddcd0d3889..f1c1d54e50 100644
--- a/.gitlab/os-linux.yml
+++ b/.gitlab/os-linux.yml
@@ -512,5 +512,8 @@
         - *before_script_linux
         - mkdir -p build/
         - cd build/
-        - cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1"
+        - cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON
+          -DCMake_SPHINX_CMAKE_ORG=ON
+          -DCMake_SPHINX_CMAKE_ORG_OUTDATED=$CMAKE_CI_SPHINX_OUTDATED
+          -DCMake_VERSION_NO_GIT=$CMAKE_CI_VERSION_NO_GIT
         - ninja
diff --git a/.gitlab/rules.yml b/.gitlab/rules.yml
index 5642c1595c..bc51d775bc 100644
--- a/.gitlab/rules.yml
+++ b/.gitlab/rules.yml
@@ -72,14 +72,21 @@
           when: on_success
         - when: never
 
-.run_only_for_continuous_master:
+.run_cmake_org_help:
     rules:
+        - if: '$CMAKE_CI_PACKAGE =~ /v[0-9]+\.[0-9]+/'
+          variables:
+              RSYNC_DESTINATION: "$CMAKE_CI_PACKAGE"
+              CMAKE_CI_VERSION_NO_GIT: "ON"
+          when: manual
         - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH'
+          variables:
+              RSYNC_DESTINATION: "git-master"
+              CMAKE_CI_VERSION_NO_GIT: "OFF"
           when: on_success
-        - when: never
-
-.run_only_for_continuous_stage:
-    rules:
         - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH'
+          variables:
+              RSYNC_DESTINATION: "git-stage"
+              CMAKE_CI_VERSION_NO_GIT: "OFF"
           when: on_success
         - when: never
diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt
index 073e5ff1a4..1dc65e7a7b 100644
--- a/Utilities/Sphinx/CMakeLists.txt
+++ b/Utilities/Sphinx/CMakeLists.txt
@@ -50,6 +50,12 @@ else()
   set(conf_copyright "Kitware, Inc.")
 endif()
 
+if(CMake_SPHINX_CMAKE_ORG)
+  set(conf_baseurl "https://cmake.org/cmake/help/latest")
+else()
+  set(conf_baseurl "")
+endif()
+
 set(conf_docs "${CMake_SOURCE_DIR}/Help")
 set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}")
 set(conf_version "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
@@ -130,11 +136,29 @@ if(SPHINX_LATEXPDF)
   list(APPEND doc_formats latexpdf)
 endif()
 
+set(doc_html_opts "")
+if(CMake_SPHINX_CMAKE_ORG)
+  list(APPEND doc_html_opts
+    -A googleanalytics=1
+    -A opensearch=1
+    -A versionswitch=1
+    )
+
+  if(CMake_SPHINX_CMAKE_ORG_OUTDATED)
+    list(APPEND doc_html_opts -A outdated=1)
+  endif()
+endif()
+
 set(doc_format_outputs "")
 set(doc_format_last "")
 foreach(format ${doc_formats})
   set(doc_format_output "doc_format_${format}")
   set(doc_format_log "build-${format}.log")
+  if(CMake_SPHINX_CMAKE_ORG)
+    set(doctrees "doctrees/${format}")
+  else()
+    set(doctrees "doctrees")
+  endif()
   if(format STREQUAL "latexpdf")
     # This format does not use builder (-b) but make_mode (-M) which expects
     # arguments in peculiar order
@@ -145,8 +169,9 @@ foreach(format ${doc_formats})
               ${CMake_SOURCE_DIR}/Help
               ${CMAKE_CURRENT_BINARY_DIR}/${format}
               -c ${CMAKE_CURRENT_BINARY_DIR}
-              -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+              -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
               ${sphinx_flags}
+              ${doc_${format}_opts}
               > ${doc_format_log} # log stdout, pass stderr
       ${${format}_extra_commands}
       DEPENDS ${doc_format_last}
@@ -159,9 +184,10 @@ foreach(format ${doc_formats})
       OUTPUT ${doc_format_output}
       COMMAND ${SPHINX_EXECUTABLE}
               -c ${CMAKE_CURRENT_BINARY_DIR}
-              -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+              -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
               -b ${format}
               ${sphinx_flags}
+              ${doc_${format}_opts}
               ${CMake_SOURCE_DIR}/Help
               ${CMAKE_CURRENT_BINARY_DIR}/${format}
               > ${doc_format_log} # log stdout, pass stderr
@@ -173,7 +199,9 @@ foreach(format ${doc_formats})
   endif()
   set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
   list(APPEND doc_format_outputs ${doc_format_output})
-  set(doc_format_last ${doc_format_output})
+  if(NOT CMake_SPHINX_CMAKE_ORG)
+    set(doc_format_last ${doc_format_output})
+  endif()
 endforeach()
 
 add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
@@ -193,6 +221,10 @@ if(CMake_SPHINX_DEPEND_ON_EXECUTABLES)
   endforeach()
 endif()
 
+if(CMake_SPHINX_CMAKE_ORG)
+  return()
+endif()
+
 if(SPHINX_INFO)
   CMake_OPTIONAL_COMPONENT(sphinx-info)
   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
diff --git a/Utilities/Sphinx/conf.py.in b/Utilities/Sphinx/conf.py.in
index c383828bd7..2b3083b046 100644
--- a/Utilities/Sphinx/conf.py.in
+++ b/Utilities/Sphinx/conf.py.in
@@ -55,6 +55,7 @@ for fpath in cmake_manuals:
 man_show_urls = False
 man_make_section_directory = False
 
+html_baseurl = '@conf_baseurl@'
 html_show_sourcelink = True
 html_static_path = ['@conf_path@/static']
 html_style = 'cmake.css'
diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css
index 029eb1b2fc..4539cf96f6 100644
--- a/Utilities/Sphinx/static/cmake.css
+++ b/Utilities/Sphinx/static/cmake.css
@@ -22,3 +22,15 @@ div.sphinxsidebarwrapper {
 dd > :first-child > p {
   margin-top: 0px;
 }
+
+div.outdated {
+  background-color: #f0f0c0;
+  color: black;
+  font-size: 90%;
+  padding-bottom: 5px;
+  padding-left: 2px;
+  padding-right: 2px;
+  padding-top: 5px;
+  text-align: center;
+  width: 100%;
+}
diff --git a/Utilities/Sphinx/templates/layout.html b/Utilities/Sphinx/templates/layout.html
index be2660caa0..8fb7c42732 100644
--- a/Utilities/Sphinx/templates/layout.html
+++ b/Utilities/Sphinx/templates/layout.html
@@ -17,10 +17,28 @@
   </li>
 {% endblock %}
 
+{%- block relbar1 %}
+{{ super() }}
+{%- if outdated is defined %}
+    <div class="outdated">
+      This documents an old version of CMake.
+      <a href="https://cmake.org/cmake/help/latest/{{ pagename }}.html">
+        Click here to see the latest release.
+      </a>
+      <span class="version_switch_note"></span>
+    </div>
+{%- endif %}
+{%- endblock %}
+
 {% block extrahead %}
-  {% if versionswitch is defined %}
-  <script type="text/javascript" src="{{ pathto('../version_switch.js', 1) }}"></script>
-  {% endif %}
+  {%- if opensearch is defined %}
+    <link rel="search" type="application/opensearchdescription+xml"
+          title="Search within CMake Documentation of Latest Version"
+          href="{{ pathto('../latest-opensearch.xml', 1) }}"/>
+  {%- endif %}
+  {%- if versionswitch is defined %}
+    <script type="text/javascript" src="{{ pathto('../version_switch.js', 1) }}"></script>
+  {%- endif %}
 {{ super() }}
 {% endblock %}
 
@@ -29,3 +47,19 @@
 {% block htmltitle %}
   <title>{{ title|striptags|e }} {{ "&mdash;"|safe }} {{ docstitle|e }}</title>
 {% endblock %}
+
+{%- block footer %}
+{{ super() }}
+{%- if googleanalytics is defined %}
+<script type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</script>
+<script type="text/javascript">
+try {
+var pageTracker = _gat._getTracker("UA-6042509-4");
+pageTracker._trackPageview();
+} catch(err) {}
+</script>
+{%- endif %}
+{%- endblock %}