Merge branch 'ci-cmake.org-help' into release-3.22

Merge-request: !7144

.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
 

.gitlab/os-linux.yml

@@ -490,5 +490,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

.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

Utilities/Sphinx/CMakeLists.txt

@@ -49,6 +49,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}")
@@ -129,11 +135,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
@@ -144,8 +168,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}
@@ -158,9 +183,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
@@ -172,7 +198,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})
@@ -192,6 +220,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

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'

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%;
+}

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 %}