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
2026-01-03 12:19:41 -06:00 · 2022-04-05 21:45:49 +00:00
parent 441860499c 2808281730
commit f38fbdb65b
7 changed files with 109 additions and 36 deletions
--- 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
+        - .run_cmake_org_help
    dependencies:
-        - b:help:master
+        - b:cmake.org-help
    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
-    dependencies:
-        - b:help:stage
-    needs:
-        - b:help:stage
+        - b:cmake.org-help

 # Lint builds

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