jazzy 0.13.2 → 0.13.7

data/README.md

@@ -1,6 +1,6 @@
 ![jazzy](images/logo.jpg)
 
-[![Build Status](https://circleci.com/gh/realm/jazzy.svg?style=svg)](https://circleci.com/gh/realm/jazzy)
+[![Build Status](https://github.com/realm/jazzy/actions/workflows/Tests.yml/badge.svg)](https://github.com/realm/jazzy/actions/workflows/Tests.yml)
 
 *jazzy is a command-line utility that generates documentation for Swift or Objective-C*
 
@@ -8,13 +8,14 @@
 
 Both Swift and Objective-C projects are supported.
 
-*SwiftPM support was recently added, so please report any issues you find.*
-
 Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
 [SourceKit][sourcekit] to use the [AST][ast] representation of your code and
 its comments for more accurate results. The output matches the look and feel
 of Apple’s official reference documentation, post WWDC 2014.
 
+Jazzy can also generate documentation from compiled swift modules [using their
+symbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.
+
 ![Screenshot](images/screenshot.jpg)
 
 This project adheres to the [Contributor Covenant Code of Conduct](https://realm.io/conduct).
@@ -49,13 +50,14 @@ succeed too!
 
 If Jazzy generates docs for the wrong module then use `--module` to tell it which
 one you'd prefer.  If this doesn't help, and you're using Xcode, then try passing
-extra arguments to `xcodebuild`, for example `jazzy --build-tool-arguments -target,MyTarget`.
+extra arguments to `xcodebuild`, for example
+`jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget`.
 
 You can set options for your project’s documentation in a configuration file,
 `.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of
 all available options, run `jazzy --help config`.
 
-### Supported keywords
+### Supported documentation keywords
 
 Swift documentation is written in markdown and supports a number of special keywords.
 For a complete list and examples, see Erica Sadun's post on [*Swift header documentation in Xcode 7*](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/),
@@ -200,6 +202,57 @@ sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
 jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
 ```
 
+### Docs from `.swiftmodule`s or frameworks
+
+*This feature is new and relies on a new Swift feature: there may be crashes
+and mistakes: reports welcome.*
+
+Swift 5.3 adds support for symbol graph generation from `.swiftmodule` files.
+This looks to be part of Apple's toolchain for generating their online docs.
+
+Jazzy can use this to generate API documentation.  This is faster than using
+the source code directly but does have limitations: for example documentation
+comments are available only for `public` declarations, and the presentation of
+Swift extensions may not match the way they are written in code.
+
+Some examples:
+
+1. Generate docs for the Apple Combine framework for macOS:
+   ```shell
+   jazzy --module Combine --swift-build-tool symbolgraph
+   ```
+   The SDK's library directories are included in the search path by
+   default.
+2. Same but for iOS:
+   ```shell
+   jazzy --module Combine --swift-build-tool symbolgraph
+         --sdk iphoneos
+         --build-tool-arguments --target,arm64-apple-ios14.1
+   ```
+   The `target` is the LLVM target triple and needs to match the SDK.  The
+   default here is the target of the host system that Jazzy is running on,
+   something like `x86_64-apple-darwin19.6.0`.
+3. Generate docs for a personal `.swiftmodule`:
+   ```shell
+   jazzy --module MyMod --swift-build-tool symbolgraph
+         --build-tool-arguments -I,/Build/Products
+   ```
+   This implies that `/Build/Products/MyMod.swiftmodule` exists.  Jazzy's
+   `--source-directory` (default current directory) is searched by default,
+   so you only need the `-I` override if that's not enough.
+4. For a personal framework:
+   ```shell
+   jazzy --module MyMod --swift-build-tool symbolgraph
+         --build-tool-arguments -F,/Build/Products
+   ```
+   This implies that `/Build/Products/MyMod.framework` exists and contains
+   a `.swiftmodule`.  Again the `--source-directory` is searched by default
+   if `-F` is not passed in.
+
+See `swift symbolgraph-extract --help` for all the things you can pass via
+`--build-tool-arguments`: if your module has dependencies then you may need
+to add various search path options to let Swift load it.
+
 ### Themes
 
 Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.
@@ -281,6 +334,13 @@ Note that the `--include` option is applied before the `--exclude` option. For e
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 
+### Documentation structure
+
+By default Jazzy does not create separate web pages for declarations that do
+not have any members: instead they are nested into some parent page.  Use the
+`--separate-global-declarations` flag to change this and always create pages
+for declarations that can be directly accessed from client code.
+
 ### Choosing the Swift language version
 
 Jazzy normally uses the Swift compiler from the Xcode currently configured by

data/Rakefile

@@ -109,6 +109,36 @@ begin
     FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
   end
 
+  #-- Theme Dependencies -----------------------------------------------------#
+
+  THEME_FILES = {
+    'jquery/dist/jquery.min.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js',
+      'themes/jony/assets/js'
+    ],
+    'lunr/lunr.min.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js'
+    ],
+    'corejs-typeahead/dist/typeahead.jquery.js' => [
+      'themes/apple/assets/js',
+      'themes/fullwidth/assets/js'
+    ],
+    'katex/dist/katex.min.css' => ['extensions/katex/css'],
+    'katex/dist/fonts' => ['extensions/katex/css'],
+    'katex/dist/katex.min.js' => ['extensions/katex/js']
+  }
+
+  desc 'Copies theme dependencies (`npm update/install` by hand first)'
+  task :theme_deps do
+    THEME_FILES.each_pair do |src, dsts|
+      dsts.each do |dst|
+        FileUtils.cp_r "js/node_modules/#{src}", "lib/jazzy/#{dst}"
+      end
+    end
+  end
+
 rescue LoadError, NameError => e
   $stderr.puts "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \

data/js/package-lock.json

@@ -0,0 +1,44 @@
+{
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "node_modules/commander": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-6.2.1.tgz",
+      "integrity": "sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/corejs-typeahead": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.1.tgz",
+      "integrity": "sha512-fyNlBNWJNL6EQUnJyAunEzBzRcwR2cEHtZXBi2pndHPOJ/wpOf3wbS+/Oh+kYYS5sKowQcs0LFwMSl6Y2Xeqkw==",
+      "dependencies": {
+        "jquery": ">=1.11"
+      }
+    },
+    "node_modules/jquery": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.0.tgz",
+      "integrity": "sha512-JVzAR/AjBvVt2BmYhxRCSYysDsPcssdmTFnzyLEts9qNwmjmu4JTAMYubEfwVOSwpQ1I1sKKFcxhZCI2buerfw=="
+    },
+    "node_modules/katex": {
+      "version": "0.13.5",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.13.5.tgz",
+      "integrity": "sha512-n2uEzFpNFUOAlWs0eCgmT82LQyP+BlS45yBgnLRqe+ENp3+FEM3lM+cJwZwwxxONFgayyq1fm6n+w35vo2MaUg==",
+      "dependencies": {
+        "commander": "^6.0.0"
+      },
+      "bin": {
+        "katex": "cli.js"
+      }
+    },
+    "node_modules/lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
+    }
+  },
+  "dependencies": {}
+}

data/js/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "jazzy-js",
+  "version": "1.0.0",
+  "description": "Jazzy theme dependencies",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "corejs-typeahead": "^1.3.1",
+    "jquery": "^3.6.0",
+    "katex": "^0.13.3",
+    "lunr": "^2.3.9"
+  }
+}

data/lib/jazzy/config.rb

@@ -59,7 +59,7 @@ module Jazzy
 
       def full_command_line_name
         long_option_names = command_line.map do |opt|
-          Regexp.last_match(1) if opt =~ %r{
+          Regexp.last_match(1) if opt.to_s =~ %r{
             ^--           # starts with double dash
             (?:\[no-\])?  # optional prefix for booleans
             ([^\s]+)      # long option name
@@ -219,14 +219,14 @@ module Jazzy
         end
       end
 
-    SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
+    SWIFT_BUILD_TOOLS = %w[spm xcodebuild symbolgraph].freeze
 
     config_attr :swift_build_tool,
       command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
-      description: 'Control whether Jazzy uses Swift Package Manager or '\
-                   'xcodebuild to build the module to be documented.  By '\
-                   'default it uses xcodebuild if there is a .xcodeproj '\
-                   'file in the source directory.',
+      description: 'Control whether Jazzy uses Swift Package Manager, '\
+                   'xcodebuild, or swift-symbolgraph to build the module '\
+                   'to be documented.  By default it uses xcodebuild if '\
+                   'there is a .xcodeproj file in the source directory.',
       parse: ->(tool) do
         return tool.to_sym if SWIFT_BUILD_TOOLS.include?(tool)
         raise "Unsupported swift_build_tool #{tool}, "\
@@ -253,7 +253,7 @@ module Jazzy
 
     config_attr :version,
       command_line: '--module-version VERSION',
-      description: 'Version string to use as part of the the default docs '\
+      description: 'Version string to use as part of the default docs '\
                    'title and inside the docset.',
       default: '1.0'
 
@@ -289,6 +289,14 @@ module Jazzy
       parse: ->(ps) { PodspecDocumenter.create_podspec(Pathname(ps)) if ps },
       default: Dir['*.podspec{,.json}'].first
 
+    config_attr :pod_sources,
+      command_line: ['--pod-sources url1,url2,…urlN', Array],
+      description: 'A list of sources to find pod dependencies. Used only '\
+                   'with --podspec when the podspec contains references to '\
+                   'privately hosted pods. You must include the default pod '\
+                   'source if public pods are also used.',
+      default: []
+
     config_attr :docset_icon,
       command_line: '--docset-icon FILEPATH',
       parse: ->(di) { expand_path(di) }
@@ -302,7 +310,8 @@ module Jazzy
     config_attr :root_url,
       command_line: ['-r', '--root-url URL'],
       description: 'Absolute URL root where these docs will be stored',
-      parse: ->(r) { URI(r) }
+      # ensure trailing slash for correct URI.join()
+      parse: ->(r) { URI(r.sub(%r{/?$}, '/')) }
 
     config_attr :dash_url,
       command_line: ['-d', '--dash_url URL'],
@@ -321,6 +330,11 @@ module Jazzy
       description: 'GitHub URL file prefix of this project (e.g. '\
                    'https://github.com/realm/realm-cocoa/tree/v0.87.1)'
 
+    config_attr :docset_playground_url,
+      command_line: '--docset-playground-url URL',
+      description: 'URL of an interactive playground to demonstrate the '\
+                   'framework, linked to from the docset.'
+
     # ──────── Doc generation options ────────
     config_attr :disable_search,
       command_line: '--disable-search',
@@ -423,6 +437,13 @@ module Jazzy
                    'is "Undocumented", put "" if no text is required',
       default: 'Undocumented'
 
+    config_attr :separate_global_declarations,
+      command_line: '--[no-]separate-global-declarations',
+      description: 'Create separate pages for all global declarations '\
+                   "(classes, structures, enums etc.) even if they don't "\
+                   'have children.',
+      default: false
+
     # rubocop:enable Style/AlignParameter
 
     def initialize

data/lib/jazzy/doc_builder.rb

@@ -14,6 +14,7 @@ require 'jazzy/source_declaration'
 require 'jazzy/source_document'
 require 'jazzy/source_module'
 require 'jazzy/sourcekitten'
+require 'jazzy/symbol_graph'
 
 module Jazzy
   # This module handles HTML generation, file writing, asset copying,
@@ -72,6 +73,8 @@ module Jazzy
       elsif options.podspec_configured
         pod_documenter = PodspecDocumenter.new(options.podspec)
         stdout = pod_documenter.sourcekitten_output(options)
+      elsif options.swift_build_tool == :symbolgraph
+        stdout = SymbolGraph.build(options)
       else
         stdout = Dir.chdir(options.source_directory) do
           arguments = SourceKitten.arguments_from_options(options)
@@ -192,7 +195,10 @@ module Jazzy
 
         lint_report = {
           warnings: warnings.sort_by do |w|
-            [w[:file], w[:line] || 0, w[:symbol], w[:symbol_kind]]
+            [w[:file] || Pathname(''),
+             w[:line] || 0,
+             w[:symbol],
+             w[:symbol_kind]]
           end,
           source_directory: options.source_directory,
         }
@@ -378,7 +384,7 @@ module Jazzy
       {
         name: mark.name,
         name_html: (render(doc_model, mark.name) if mark.name),
-        uid: URI.encode(uid),
+        uid: ERB::Util.url_encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
         post_separator: mark.has_end_dash,
@@ -432,12 +438,18 @@ module Jazzy
       doc[:kind] = doc_model.type.name
       doc[:dash_type] = doc_model.type.dash_type
       doc[:declaration] = doc_model.display_declaration
+      doc[:language] = doc_model.display_language
+      doc[:other_language_declaration] =
+        doc_model.display_other_language_declaration
       doc[:overview] = overview
+      doc[:parameters] = doc_model.parameters
+      doc[:return] = doc_model.return
       doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url
+      doc[:github_token_url] = gh_token_url(doc_model, source_module)
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:deprecation_message] = doc_model.deprecation_message

data/lib/jazzy/docset_builder.rb

@@ -43,6 +43,8 @@ module Jazzy
             template.read,
             lowercase_name: source_module.name.downcase,
             name: source_module.name,
+            root_url: config.root_url,
+            playground_url: config.docset_playground_url,
           )
         end
       end

data/lib/jazzy/docset_builder/info_plist.mustache

@@ -16,5 +16,13 @@
       <true/>
     <key>DashDocSetFamily</key>
       <string>dashtoc</string>
+    {{#root_url}}
+    <key>DashDocSetFallbackURL</key>
+      <string>{{{.}}}</string>
+    {{/root_url}}
+    {{#playground_url}}
+    <key>DashDocSetPlayURL</key>
+      <string>{{{.}}}</string>
+    {{/playground_url}}
   </dict>
 </plist>