Merge pull request #76152 from swiftlang/QuietMisdreavus/stdlib-docs

add build-script flags to build/preview stdlib docs with Swift-DocC

Author: QuietMisdreavus

CMakeLists.txt

@@ -463,6 +463,10 @@ option(SWIFT_STDLIB_ENABLE_SIB_TARGETS
        "Should we generate sib targets for the stdlib or not?"
        FALSE)
 
+option(SWIFT_STDLIB_BUILD_SYMBOL_GRAPHS
+       "Whether to build symbol graphs for the stdlib, for use in documentation."
+       FALSE)
+
 
 set(SWIFT_DARWIN_SUPPORTED_ARCHS "" CACHE STRING
   "Semicolon-separated list of architectures to configure on Darwin platforms. \

stdlib/cmake/modules/AddSwiftStdlib.cmake

@@ -937,6 +937,13 @@ function(add_swift_target_library_single target name)
     set(SWIFTLIB_SINGLE_SOURCES ${SWIFTLIB_SINGLE_SOURCES} ${SWIFTLIB_SINGLE_HEADERS} ${SWIFTLIB_SINGLE_TDS})
   endif()
 
+  # FIXME: swiftDarwin currently trips an assertion in SymbolGraphGen
+  if (SWIFTLIB_IS_STDLIB AND SWIFT_STDLIB_BUILD_SYMBOL_GRAPHS AND NOT ${name} STREQUAL "swiftDarwin")
+    list(APPEND SWIFTLIB_SINGLE_SWIFT_COMPILE_FLAGS "-Xfrontend;-emit-symbol-graph")
+    list(APPEND SWIFTLIB_SINGLE_SWIFT_COMPILE_FLAGS
+         "-Xfrontend;-emit-symbol-graph-dir;-Xfrontend;${out_lib_dir}/symbol-graph/${VARIANT_NAME}")
+  endif()
+
   if(MODULE)
     set(libkind MODULE)
   elseif(SWIFTLIB_SINGLE_OBJECT_LIBRARY)
@@ -2233,7 +2240,6 @@ function(add_swift_target_library name)
       endif()
     endif()
 
-
     # Collect architecture agnostic SDK linker flags
     set(swiftlib_link_flags_all ${SWIFTLIB_LINK_FLAGS})
     if(sdk STREQUAL "IOS_SIMULATOR" AND name STREQUAL "swiftMediaPlayer")

utils/build_swift/build_swift/driver_arguments.py

@@ -60,6 +60,10 @@ def _apply_default_arguments(args):
     if args.build_linux_static and args.build_libcxx is None:
         args.build_libcxx = True
 
+    # Previewing the stdlib docs requires building them.
+    if args.preview_stdlib_docs:
+        args.build_stdlib_docs = True
+
     # Set the default CMake generator.
     if args.cmake_generator is None:
         args.cmake_generator = 'Ninja'
@@ -1160,6 +1164,15 @@ def create_argument_parser():
            help='Include Unicode data in the standard library.'
                 'Note: required for full String functionality')
 
+    option('--build-stdlib-docs', toggle_true,
+           default=False,
+           help='Build documentation for the standard library.'
+                'Note: this builds Swift-DocC to perform the docs build.')
+    option('--preview-stdlib-docs', toggle_true,
+           default=False,
+           help='Build and preview standard library documentation with Swift-DocC.'
+                'Note: this builds Swift-DocC to perform the docs build.')
+
     option('--build-swift-clang-overlays', toggle_true,
            default=True,
            help='Build Swift overlays for the clang builtin modules')

utils/build_swift/tests/expected_options.py

@@ -274,6 +274,8 @@
     'swift_tools_max_parallel_lto_link_jobs':
         defaults.SWIFT_MAX_PARALLEL_LTO_LINK_JOBS,
     'swift_user_visible_version': defaults.SWIFT_USER_VISIBLE_VERSION,
+    'build_stdlib_docs': False,
+    'preview_stdlib_docs': False,
     'symbols_package': None,
     'clean_libdispatch': True,
     'clean_foundation': True,
@@ -578,6 +580,8 @@ class BuildScriptImplOption(_BaseOption):
     SetTrueOption('--build-minimal-stdlib', dest='build_minimalstdlib'),
     SetTrueOption('--build-wasm-stdlib', dest='build_wasmstdlib'),
     SetTrueOption('--wasmkit', dest='build_wasmkit'),
+    SetTrueOption('--build-stdlib-docs'),
+    SetTrueOption('--preview-stdlib-docs'),
     SetTrueOption('-B', dest='benchmark'),
     SetTrueOption('-S', dest='skip_build'),
     SetTrueOption('-b', dest='build_llbuild'),

utils/swift_build_support/swift_build_support/build_script_invocation.py

@@ -700,11 +700,19 @@ def compute_product_pipelines(self):
                             is_enabled=self.args.tsan_libdispatch_test)
         builder.add_product(products.SwiftDocC,
                             is_enabled=self.args.build_swiftdocc)
-        builder.add_product(products.SwiftDocCRender,
-                            is_enabled=self.args.install_swiftdocc)
         builder.add_product(products.MinimalStdlib,
                             is_enabled=self.args.build_minimalstdlib)
 
+        # Swift-DocC-Render should be installed whenever Swift-DocC is installed, which
+        # can be either given directly or via install-all
+        install_doccrender = self.args.install_swiftdocc or (
+            self.args.install_all and self.args.build_swiftdocc
+        )
+        builder.add_product(products.SwiftDocCRender,
+                            is_enabled=install_doccrender)
+        builder.add_product(products.StdlibDocs,
+                            is_enabled=self.args.build_stdlib_docs)
+
         # Keep SwiftDriver at last.
         # swift-driver's integration with the build scripts is not fully
         # supported. Using swift-driver to build these products may hit

utils/swift_build_support/swift_build_support/products/__init__.py

@@ -29,6 +29,7 @@
 from .skstresstester import SKStressTester
 from .sourcekitlsp import SourceKitLSP
 from .staticswiftlinux import StaticSwiftLinuxConfig
+from .stdlib_docs import StdlibDocs
 from .swift import Swift
 from .swift_testing import SwiftTesting
 from .swift_testing_macros import SwiftTestingMacros
@@ -65,6 +66,7 @@
     'Ninja',
     'PlaygroundSupport',
     'StaticSwiftLinuxConfig',
+    'StdlibDocs',
     'Swift',
     'SwiftFormat',
     'SwiftInspect',

utils/swift_build_support/swift_build_support/products/stdlib_docs.py

@@ -0,0 +1,79 @@
+# swift_build_support/products/stdlib_docs.py -------------------*- python -*-
+#
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See https://swift.org/LICENSE.txt for license information
+# See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+#
+# ----------------------------------------------------------------------------
+
+import os
+
+from . import product
+from . import swiftdocc
+from . import swiftdoccrender
+from .. import shell
+
+
+class StdlibDocs(product.Product):
+    @classmethod
+    def is_build_script_impl_product(cls):
+        return False
+
+    @classmethod
+    def is_before_build_script_impl_product(cls):
+        return False
+
+    @classmethod
+    def is_swiftpm_unified_build_product(cls):
+        return False
+
+    def should_build(self, host_target):
+        return self.args.build_stdlib_docs
+
+    def build(self, host_target):
+        toolchain_path = self.install_toolchain_path(host_target)
+        docc_path = os.path.join(toolchain_path, "bin", "docc")
+
+        swift_build_dir = os.path.join(
+            os.path.dirname(self.build_dir),
+            f'swift-{host_target}'
+        )
+        symbol_graph_dir = os.path.join(swift_build_dir, "lib", "symbol-graph")
+        output_path = os.path.join(swift_build_dir, "Swift.doccarchive")
+
+        docc_action = 'preview' if self.args.preview_stdlib_docs else 'convert'
+
+        docc_cmd = [
+            docc_path,
+            docc_action,
+            "--additional-symbol-graph-dir",
+            symbol_graph_dir,
+            "--output-path",
+            output_path,
+            "--default-code-listing-language",
+            "swift",
+            "--fallback-display-name",
+            "Swift",
+            "--fallback-bundle-identifier",
+            "org.swift.swift",
+        ]
+
+        shell.call(docc_cmd)
+
+    def should_test(self, host_target):
+        return False
+
+    def should_install(self, host_target):
+        return False
+
+    @classmethod
+    def get_dependencies(cls):
+        """Return a list of products that this product depends upon"""
+        return [
+            swiftdocc.SwiftDocC,
+            swiftdoccrender.SwiftDocCRender
+        ]

utils/swift_build_support/swift_build_support/products/swift.py

@@ -89,6 +89,8 @@ def __init__(self, args, toolchain, source_dir, build_dir):
 
         self.cmake_options.extend(self._enable_embedded_stdlib_cross_compiling)
 
+        self.cmake_options.extend(self._enable_stdlib_symbol_graphs)
+
         self.cmake_options.extend(
             self._swift_tools_ld64_lto_codegen_only_for_supporting_targets)
 
@@ -271,6 +273,11 @@ def _enable_embedded_stdlib_cross_compiling(self):
         return [('SWIFT_SHOULD_BUILD_EMBEDDED_STDLIB_CROSS_COMPILING',
                  self.args.build_embedded_stdlib_cross_compiling)]
 
+    @property
+    def _enable_stdlib_symbol_graphs(self):
+        return [('SWIFT_STDLIB_BUILD_SYMBOL_GRAPHS:BOOL',
+                 self.args.build_stdlib_docs)]
+
     def _handle_swift_debuginfo_non_lto_args(self):
         if ('swift_debuginfo_non_lto_args' not in self.args
                 or self.args.swift_debuginfo_non_lto_args is None):

utils/swift_build_support/swift_build_support/products/swiftdoccrender.py

@@ -48,7 +48,9 @@ def should_test(self, host_target):
 
     def should_install(self, host_target):
         # Swift-DocC-Render should always be installed if Swift-DocC is being installed
-        return self.args.install_swiftdocc
+        return self.args.install_swiftdocc or (
+            self.args.install_all and self.args.build_swiftdocc
+        )
 
     def install(self, host_target):
         # Swift-DocC-Render is installed at '/usr/share/docc/render' in the built

utils/swift_build_support/tests/products/test_swift.py

@@ -71,7 +71,8 @@ def setUp(self):
             build_embedded_stdlib_cross_compiling=False,
             swift_freestanding_is_darwin=False,
             build_swift_private_stdlib=True,
-            swift_tools_ld64_lto_codegen_only_for_supporting_targets=False)
+            swift_tools_ld64_lto_codegen_only_for_supporting_targets=False,
+            build_stdlib_docs=False)
 
         # Setup shell
         shell.dry_run = True
@@ -120,7 +121,8 @@ def test_by_default_no_cmake_options(self):
             '-DSWIFT_SHOULD_BUILD_EMBEDDED_STDLIB=TRUE',
             '-DSWIFT_SHOULD_BUILD_EMBEDDED_STDLIB_CROSS_COMPILING=FALSE',
             '-DSWIFT_TOOLS_LD64_LTO_CODEGEN_ONLY_FOR_SUPPORTING_TARGETS:BOOL=FALSE',
-            '-USWIFT_DEBUGINFO_NON_LTO_ARGS'
+            '-USWIFT_DEBUGINFO_NON_LTO_ARGS',
+            '-DSWIFT_STDLIB_BUILD_SYMBOL_GRAPHS:BOOL=FALSE'
         ]
         self.assertEqual(set(swift.cmake_options), set(expected))
 
@@ -154,7 +156,8 @@ def test_swift_runtime_tsan(self):
             '-DSWIFT_SHOULD_BUILD_EMBEDDED_STDLIB=TRUE',
             '-DSWIFT_SHOULD_BUILD_EMBEDDED_STDLIB_CROSS_COMPILING=FALSE',
             '-DSWIFT_TOOLS_LD64_LTO_CODEGEN_ONLY_FOR_SUPPORTING_TARGETS:BOOL=FALSE',
-            '-USWIFT_DEBUGINFO_NON_LTO_ARGS'
+            '-USWIFT_DEBUGINFO_NON_LTO_ARGS',
+            '-DSWIFT_STDLIB_BUILD_SYMBOL_GRAPHS:BOOL=FALSE'
         ]
         self.assertEqual(set(swift.cmake_options), set(flags_set))
 
@@ -567,3 +570,16 @@ def test_swift_debuginfo_non_lto_args(self):
              '-gline-tables-only;-v'],
             [x for x in swift.cmake_options
                 if 'SWIFT_DEBUGINFO_NON_LTO_ARGS' in x])
+
+    def test_stdlib_docs_flags(self):
+        self.args.build_stdlib_docs = True
+        swift = Swift(
+            args=self.args,
+            toolchain=self.toolchain,
+            source_dir='/path/to/src',
+            build_dir='/path/to/build')
+        self.assertEqual(
+            ['-DSWIFT_STDLIB_BUILD_SYMBOL_GRAPHS:BOOL='
+             'TRUE'],
+            [x for x in swift.cmake_options
+             if 'DSWIFT_STDLIB_BUILD_SYMBOL_GRAPHS' in x])