CMake: Re-work documentation targets

The top-level prepare_docs target is supposed to run before the
generate_docs target.

The repository-level targets like prepare_docs_qtbase now also run
before their respective generate targets.

To achieve that, several intermediate targets had to be introduced.
The dependencies for top-level generate_docs look like this:

              /--> generate_top_level_docs_Core --\
generate_docs ---> generate_top_level_docs_Gui  -----> prepare_docs
              \--> ...                          --/

The dependencies for repo-level generate_docs_<repo> look like this:

                     /--> generate_repo_docs_Core
generate_docs_qtbase ---> generate_repo_docs_Gui
                     \--> ...

generate_repo_docs_Core --\
generate_repo_docs_Gui  -----> prepare_docs_qtbase
...                     --/

Analoguous for qch_docs.

And last but not least, the module-level generate_docs_<module> depends
on prepare_docs_<module>, just like before.

The strangely named top-level install targets have been renamed to
install_html_docs, install_qch_docs and install_docs.

The html_docs target is now merely an alias for generate_docs.

Apart from prepare_docs, the top-level targets do not depend on the
repository-level targets anymore. Targets that are just an alias (docs,
install_docs, ...) have been re-defined to depend just on the respective
top-level targets.

Fixes: QTBUG-87758
Change-Id: I24466d3a252d518a30a2064bf876be881c46231f
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

2 files changed, 31 insertions, 30 deletions

diff --git a/cmake/QtBuildInternals/QtBuildInternalsConfig.cmake b/cmake/QtBuildInternals/QtBuildInternalsConfig.cmake
index 40d495d414..56e7e99d63 100644
--- a/cmake/QtBuildInternals/QtBuildInternalsConfig.cmake
+++ b/cmake/QtBuildInternals/QtBuildInternalsConfig.cmake
@@ -230,9 +230,14 @@ macro(qt_build_repo_begin)
         add_custom_target(generate_docs)
         add_custom_target(html_docs)
         add_custom_target(qch_docs)
-        add_custom_target(install_html_docs_docs)
-        add_custom_target(install_qch_docs_docs)
-        add_custom_target(install_docs_docs)
+        add_custom_target(install_html_docs)
+        add_custom_target(install_qch_docs)
+        add_custom_target(install_docs)
+        add_dependencies(html_docs generate_docs)
+        add_dependencies(docs html_docs qch_docs)
+        add_dependencies(install_html_docs html_docs)
+        add_dependencies(install_qch_docs qch_docs)
+        add_dependencies(install_docs install_html_docs install_qch_docs)
     endif()
 
     # Add global qt_plugins, qpa_plugins and qpa_default_plugins convenience custom targets.
@@ -267,19 +272,13 @@ macro(qt_build_repo_begin)
 
     add_dependencies(${qt_docs_generate_target_name} ${qt_docs_prepare_target_name})
     add_dependencies(${qt_docs_html_target_name} ${qt_docs_generate_target_name})
+    add_dependencies(${qt_docs_target_name} ${qt_docs_html_target_name} ${qt_docs_qch_target_name})
     add_dependencies(${qt_docs_install_html_target_name} ${qt_docs_html_target_name})
     add_dependencies(${qt_docs_install_qch_target_name} ${qt_docs_qch_target_name})
     add_dependencies(${qt_docs_install_target_name} ${qt_docs_install_html_target_name} ${qt_docs_install_qch_target_name})
 
-    # Make global doc targets depend on the module ones.
-    add_dependencies(docs ${qt_docs_target_name})
+    # Make top-level prepare_docs target depend on the repository-level prepare_docs_<repo> target.
     add_dependencies(prepare_docs ${qt_docs_prepare_target_name})
-    add_dependencies(generate_docs ${qt_docs_generate_target_name})
-    add_dependencies(html_docs ${qt_docs_html_target_name})
-    add_dependencies(qch_docs ${qt_docs_qch_target_name})
-    add_dependencies(install_html_docs_docs ${qt_docs_install_html_target_name})
-    add_dependencies(install_qch_docs_docs ${qt_docs_install_qch_target_name})
-    add_dependencies(install_docs_docs ${qt_docs_install_target_name})
 
     # Add host_tools meta target, so that developrs can easily build only tools and their
     # dependencies when working in qtbase.
diff --git a/cmake/QtDocsHelpers.cmake b/cmake/QtDocsHelpers.cmake
index 7a635eea03..f65fd4a07d 100644
--- a/cmake/QtDocsHelpers.cmake
+++ b/cmake/QtDocsHelpers.cmake
@@ -131,14 +131,16 @@ function(qt_internal_add_docs)
         "${include_path_args}"
     )
 
-    add_custom_target(generate_docs_${target}
-        DEPENDS ${qdoc_bin}
-        COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
-        ${qdoc_bin}
-        ${generate_qdocs_args}
-    )
+    foreach(target_prefix generate_top_level_docs generate_repo_docs generate_docs)
+        add_custom_target(${target_prefix}_${target}
+            DEPENDS ${qdoc_bin}
+            COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args} ${qdoc_bin} ${generate_qdocs_args})
+    endforeach()
 
     add_dependencies(generate_docs_${target} prepare_docs_${target})
+    add_dependencies(generate_repo_docs_${target} ${qt_docs_prepare_target_name})
+    add_dependencies(generate_top_level_docs_${target} prepare_docs)
+    add_dependencies(generate_docs generate_top_level_docs_${target})
 
     # html docs target
     add_custom_target(html_docs_${target})
@@ -148,13 +150,18 @@ function(qt_internal_add_docs)
     set(qch_file_name ${doc_target}.qch)
     set(qch_file_path ${qdoc_output_dir}/${qch_file_name})
 
-    add_custom_target(qch_docs_${target}
-        DEPENDS ${qhelpgenerator_bin}
-        COMMAND ${qhelpgenerator_bin}
-           "${qdoc_output_dir}/${doc_target}.qhp"
-           -o "${qch_file_path}"
-    )
+    foreach(target_prefix qch_top_level_docs qch_repo_docs qch_docs)
+        add_custom_target(${target_prefix}_${target}
+            DEPENDS ${qhelpgenerator_bin}
+            COMMAND ${qhelpgenerator_bin}
+            "${qdoc_output_dir}/${doc_target}.qhp"
+            -o "${qch_file_path}"
+        )
+    endforeach()
     add_dependencies(qch_docs_${target} generate_docs_${target})
+    add_dependencies(qch_repo_docs_${target} ${qt_docs_generate_target_name})
+    add_dependencies(qch_top_level_docs_${target} generate_docs)
+    add_dependencies(qch_docs qch_top_level_docs_${target})
 
     if (QT_WILL_INSTALL)
         add_custom_target(install_html_docs_${target}
@@ -187,13 +194,8 @@ function(qt_internal_add_docs)
     add_dependencies(docs_${target} qch_docs_${target})
 
     add_dependencies(${qt_docs_prepare_target_name} prepare_docs_${target})
-    add_dependencies(${qt_docs_generate_target_name} generate_docs_${target})
-    add_dependencies(${qt_docs_html_target_name} html_docs_${target})
-    add_dependencies(${qt_docs_qch_target_name} qch_docs_${target})
-    add_dependencies(${qt_docs_target_name} docs_${target})
-    add_dependencies(${qt_docs_install_html_target_name} install_html_docs_${target})
-    add_dependencies(${qt_docs_install_qch_target_name} install_qch_docs_${target})
-    add_dependencies(${qt_docs_install_target_name} install_docs_${target})
+    add_dependencies(${qt_docs_generate_target_name} generate_repo_docs_${target})
+    add_dependencies(${qt_docs_qch_target_name} qch_repo_docs_${target})
 
     # Make sure that the necessary tools are built when running,
     # for example 'cmake --build . --target generate_docs'.