doc: skip the documentation build by default

This reverse the current approach of building the documentation
by default, and replace the skip-docs parameter by a build-docs one.

A warning is printed when the --skip-docs is used,
and another warning is displayed when using --doc-build-online
without the --build-docs option.

Change-Id: I2bf8302881b51e9831795a7e881b106022cdffa8
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

4 files changed, 29 insertions, 12 deletions

diff --git a/build_scripts/main.py b/build_scripts/main.py
index 75850691b..d44fa2f76 100644
--- a/build_scripts/main.py
+++ b/build_scripts/main.py
@@ -642,7 +642,10 @@ class PysideBuild(_build, DistUtilsCommandMixin, BuildInfoCollectorMixin):
         if OPTION['NO_QT_TOOLS']:
             cmake_cmd.append("-DNO_QT_TOOLS=yes")
         if OPTION['SKIP_DOCS']:
-            cmake_cmd.append("-DSKIP_DOCS=yes")
+            log.info(f"Warning: '--skip-docs' is deprecated and will be removed. "
+                     "The documentation is not built by default")
+        if OPTION['BUILD_DOCS']:
+            cmake_cmd.append("-DBUILD_DOCS=yes")
         log.info(f"Qt Source dir: {cmake_src_dir}")
 
         # Use Legacy OpenGL to avoid issues on systems like Ubuntu 20.04
@@ -757,7 +760,7 @@ class PysideBuild(_build, DistUtilsCommandMixin, BuildInfoCollectorMixin):
             cmake_cmd.append(f"-DCMAKE_OSX_DEPLOYMENT_TARGET={deployment_target}")
             os.environ['MACOSX_DEPLOYMENT_TARGET'] = deployment_target
 
-        if not OPTION["SKIP_DOCS"]:
+        if OPTION["BUILD_DOCS"]:
             # Build the whole documentation (rst + API) by default
             cmake_cmd.append("-DFULLDOCSBUILD=1")
 
@@ -768,7 +771,11 @@ class PysideBuild(_build, DistUtilsCommandMixin, BuildInfoCollectorMixin):
                 log.info("Output format will be qthelp")
                 cmake_cmd.append("-DDOC_OUTPUT_FORMAT=qthelp")
         else:
-            cmake_cmd.append("-DSKIP_DOCS=1")
+            cmake_cmd.append("-DBUILD_DOCS=no")
+            if OPTION["DOC_BUILD_ONLINE"]:
+                log.info("Warning: Documentation build is disabled, "
+                         "however --doc-build-online was passed. "
+                         "Use '--build-docs' to enable the documentation build")
 
         if OPTION["PYSIDE_NUMPY_SUPPORT"]:
             cmake_cmd.append("-DPYSIDE_NUMPY_SUPPORT=1")
@@ -819,7 +826,7 @@ class PysideBuild(_build, DistUtilsCommandMixin, BuildInfoCollectorMixin):
             if "UTF-8" not in os.environ.get("LC_ALL", ""):
                 os.environ["LC_ALL"] = "en_US.UTF-8"
 
-        if not OPTION["SKIP_DOCS"]:
+        if OPTION["BUILD_DOCS"]:
             if extension.lower() == SHIBOKEN:
                 found = importlib.util.find_spec("sphinx")
                 if found:
@@ -833,8 +840,8 @@ class PysideBuild(_build, DistUtilsCommandMixin, BuildInfoCollectorMixin):
                 else:
                     log.info("Sphinx not found, skipping documentation build")
         else:
-            log.info("Skipped documentation generation")
-            cmake_cmd.append("-DSKIP_DOCS=1")
+            log.info("-- Skipped documentation generation. Enable with '--build-docs'")
+            cmake_cmd.append("-DBUILD_DOCS=no")
 
         if not OPTION["SKIP_MAKE_INSTALL"]:
             log.info(f"Installing module {extension}...")
diff --git a/build_scripts/options.py b/build_scripts/options.py
index b33e27857..0cb80e6ce 100644
--- a/build_scripts/options.py
+++ b/build_scripts/options.py
@@ -211,7 +211,8 @@ class DistUtilsCommandMixin(object):
         ('no-strip', None, 'Do not strip package libraries (release mode)'),
         ('standalone', None, 'Standalone build'),
         ('ignore-git', None, 'Do update subrepositories'),
-        ('skip-docs', None, 'Skip documentation build'),
+        ('skip-docs', None, 'Skip documentation build (deprecated)'),
+        ('build-docs', None, 'Build the API documentation'),
         ('no-examples', None, 'Do not build examples'),
         ('no-jom', None, 'Do not use jom (MSVC)'),
         ('build-tests', None, 'Build tests'),
@@ -266,6 +267,7 @@ class DistUtilsCommandMixin(object):
         self.standalone = False
         self.ignore_git = False
         self.skip_docs = False
+        self.build_docs = False
         self.no_examples = False
         self.no_jom = False
         self.build_tests = False
@@ -371,6 +373,7 @@ class DistUtilsCommandMixin(object):
         OPTION['STANDALONE'] = self.standalone
         OPTION['IGNOREGIT'] = self.ignore_git
         OPTION['SKIP_DOCS'] = self.skip_docs
+        OPTION['BUILD_DOCS'] = self.build_docs
         OPTION['NOEXAMPLES'] = self.no_examples
         OPTION['BUILDTESTS'] = self.build_tests
         OPTION['NO_JOM'] = self.no_jom
diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt
index 7bc1424bf..9d4fcf144 100644
--- a/sources/pyside6/doc/CMakeLists.txt
+++ b/sources/pyside6/doc/CMakeLists.txt
@@ -8,7 +8,7 @@ include(FindDocTools)
 # When the doc project is built as part of the pyside project, we show informational message
 # and return early if requirements are not met.
 if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
-    if(QT_SRC_DIR AND SPHINX_BUILD AND DOT_EXEC AND NOT SKIP_DOCS)
+    if(QT_SRC_DIR AND SPHINX_BUILD AND DOT_EXEC AND BUILD_DOCS)
         # All requirements met, proceed.
     else()
         set(reasons "")
@@ -21,8 +21,8 @@ if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
         if(NOT DOT_EXEC)
             list(APPEND reasons "    graphviz not found\n")
         endif()
-        if(SKIP_DOCS)
-            list(APPEND reasons "    SKIP_DOCS was set to TRUE\n")
+        if(NOT BUILD_DOCS)
+            list(APPEND reasons "    BUILD_DOCS was set to FALSE (default)\n")
         endif()
         message(STATUS "apidoc generation targets disabled due to the following reasons:\n"
                 ${reasons})
diff --git a/sources/pyside6/doc/gettingstarted.rst b/sources/pyside6/doc/gettingstarted.rst
index 497b9afa8..1a465b79c 100644
--- a/sources/pyside6/doc/gettingstarted.rst
+++ b/sources/pyside6/doc/gettingstarted.rst
@@ -75,7 +75,9 @@ Other important options to consider are:
  * ``--openssl=/path/to/openssl/bin``, to use a different path for OpenSSL,
  * ``--standalone``, to copy over the Qt libraries into the final package to make it work on other
    machines,
- * ``--doc-build-online``, to build documentation using the online template.
+ * ``--build-docs``, to enable the documentation build.
+ * ``--doc-build-online``, to build documentation using the online template (by
+   default it uses the offline)
 
 Testing the installation
 ------------------------
@@ -355,6 +357,10 @@ Troubleshooting
 Building the documentation
 --------------------------
 
+Starting from 6.3, the documentation is not being built by default.
+When using the second option described in this section, make sure to use the
+``--build-docs`` option.
+
 Starting from 5.15, there are two options to build the documentation:
 
 1. Building rst-only documentation (no API)
@@ -403,7 +409,8 @@ Since the process relies on a Qt installation, you need to specify where the
 
     export QT_SRC_DIR=/path/to/qtbase
 
-Once the build process finishes, you can go to the generated ``*_build/*_release/pyside6``
+Once the common ``setup.py`` build process finishes (remember to use ``--build-docs`` to enable
+the documentation build), you can go to the generated ``*_build/*_release/pyside6``
 directory, and run::
 
     ninja apidoc