From cca73b54ae6a25f50b17cf32077ca85020340d92 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 1 Apr 2022 21:47:42 -0400 Subject: Utilities/Sphinx: Add undocumented option to build docs for cmake.org --- .gitlab/os-linux.yml | 3 ++- Utilities/Sphinx/CMakeLists.txt | 33 ++++++++++++++++++++++++++++++--- Utilities/Sphinx/conf.py.in | 1 + Utilities/Sphinx/templates/layout.html | 22 +++++++++++++++++++--- 4 files changed, 52 insertions(+), 7 deletions(-) diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 90c10a2..48d4279 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -490,5 +490,6 @@ - *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 - ninja diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index c8a970d..6576036 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/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,24 @@ 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 versionswitch=1 + ) +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 +163,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 +178,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 +193,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 +215,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 c383828..2b3083b 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/templates/layout.html b/Utilities/Sphinx/templates/layout.html index be2660c..0cc5c26 100644 --- a/Utilities/Sphinx/templates/layout.html +++ b/Utilities/Sphinx/templates/layout.html @@ -18,9 +18,9 @@ {% endblock %} {% block extrahead %} - {% if versionswitch is defined %} - - {% endif %} + {%- if versionswitch is defined %} + + {%- endif %} {{ super() }} {% endblock %} @@ -29,3 +29,19 @@ {% block htmltitle %} {{ title|striptags|e }} {{ "—"|safe }} {{ docstitle|e }} {% endblock %} + +{%- block footer %} +{{ super() }} +{%- if googleanalytics is defined %} + + +{%- endif %} +{%- endblock %} -- cgit v0.12 From a14905d4df6c47dbcd574f05ad0a324906dd1329 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 1 Apr 2022 22:09:50 -0400 Subject: Utilities/Sphinx: Add option to build outdated version banner for cmake.org This was previously added in a custom branch for building the cmake.org reference documentation. --- .gitlab/os-linux.yml | 1 + Utilities/Sphinx/CMakeLists.txt | 4 ++++ Utilities/Sphinx/static/cmake.css | 12 ++++++++++++ Utilities/Sphinx/templates/layout.html | 13 +++++++++++++ 4 files changed, 30 insertions(+) diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 48d4279..4a87b21 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -492,4 +492,5 @@ - cd build/ - cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DCMake_SPHINX_CMAKE_ORG=ON + -DCMake_SPHINX_CMAKE_ORG_OUTDATED=$CMAKE_CI_SPHINX_OUTDATED - ninja diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index 6576036..dd70ce6 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -141,6 +141,10 @@ if(CMake_SPHINX_CMAKE_ORG) -A googleanalytics=1 -A versionswitch=1 ) + + if(CMake_SPHINX_CMAKE_ORG_OUTDATED) + list(APPEND doc_html_opts -A outdated=1) + endif() endif() set(doc_format_outputs "") diff --git a/Utilities/Sphinx/static/cmake.css b/Utilities/Sphinx/static/cmake.css index 029eb1b..4539cf9 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 0cc5c26..d02b44d 100644 --- a/Utilities/Sphinx/templates/layout.html +++ b/Utilities/Sphinx/templates/layout.html @@ -17,6 +17,19 @@ {% endblock %} +{%- block relbar1 %} +{{ super() }} +{%- if outdated is defined %} +
+ This documents an old version of CMake. + + Click here to see the latest release. + + +
+{%- endif %} +{%- endblock %} + {% block extrahead %} {%- if versionswitch is defined %} -- cgit v0.12 From 5c2e8ce515bc1f47ac6dd6d5b55bfe7f45190a02 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 1 Apr 2022 22:12:41 -0400 Subject: Utilities/Sphinx: Add OpenSearch link to html page headers on cmake.org Reference an OpenSearch description file that sits outside the content of any specific version so we only need to maintain one and so that it can reference the latest version. This was previously added in a custom branch for building the cmake.org reference documentation. --- Utilities/Sphinx/CMakeLists.txt | 1 + Utilities/Sphinx/templates/layout.html | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index dd70ce6..14d0e14 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -139,6 +139,7 @@ set(doc_html_opts "") if(CMake_SPHINX_CMAKE_ORG) list(APPEND doc_html_opts -A googleanalytics=1 + -A opensearch=1 -A versionswitch=1 ) diff --git a/Utilities/Sphinx/templates/layout.html b/Utilities/Sphinx/templates/layout.html index d02b44d..8fb7c42 100644 --- a/Utilities/Sphinx/templates/layout.html +++ b/Utilities/Sphinx/templates/layout.html @@ -31,6 +31,11 @@ {%- endblock %} {% block extrahead %} + {%- if opensearch is defined %} + + {%- endif %} {%- if versionswitch is defined %} {%- endif %} -- cgit v0.12 From ed00a29ccef7d1a6757c040cf10e9cb720080340 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 4 Apr 2022 12:04:35 -0400 Subject: gitlab-ci: consolidate jobs for cmake.org/cmake/help/git-{master,stage} docs --- .gitlab-ci.yml | 30 ++++++------------------------ .gitlab/rules.yml | 10 +++++----- 2 files changed, 11 insertions(+), 29 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d5529df..0585579 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -70,37 +70,19 @@ 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 -.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/rules.yml b/.gitlab/rules.yml index 5642c15..def89a0 100644 --- a/.gitlab/rules.yml +++ b/.gitlab/rules.yml @@ -72,14 +72,14 @@ when: on_success - when: never -.run_only_for_continuous_master: +.run_cmake_org_help: rules: - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH' + variables: + RSYNC_DESTINATION: "git-master" 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" when: on_success - when: never -- cgit v0.12 From 2808281730b2c887da1845f86042566991be5a8a Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 4 Apr 2022 13:52:04 -0400 Subject: gitlab-ci: update cmake.org documentation in release package pipeline --- .gitlab-ci.yml | 2 ++ .gitlab/os-linux.yml | 1 + .gitlab/rules.yml | 7 +++++++ 3 files changed, 10 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0585579..60b1beb 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -74,6 +74,8 @@ b:cmake.org-help: extends: - .cmake_org_help - .run_cmake_org_help + dependencies: [] + needs: [] u:cmake.org-help: extends: diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 4a87b21..3d2c827 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -493,4 +493,5 @@ - 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 def89a0..bc51d77 100644 --- a/.gitlab/rules.yml +++ b/.gitlab/rules.yml @@ -74,12 +74,19 @@ .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 - 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 -- cgit v0.12