jazzy 0.14.2 → 0.14.4

data/README.md

@@ -214,16 +214,14 @@ sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
       -I $(pwd) -fmodules > objcDoc.json
 
 # Feed both outputs to Jazzy as a comma-separated list
-jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
+jazzy --module MyProject --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.*
+*This feature is new: 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.
+Swift 5.3 added support for symbol graph generation from `.swiftmodule` files.
 
 Jazzy can use this to generate API documentation.  This is faster than using
 the source code directly but does have limitations: for example documentation
@@ -360,25 +358,69 @@ 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.
 
+Declarations with the `@_documentation(visibility:)` attribute are treated as though they
+are written with the given visibility.  You can use this as a replacement for `:nodoc:` as
+part of a transition to Apple's DocC but it is not compatible with Jazzy's symbolgraph mode.
+
 ### 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.
+Jazzy arranges documentation into categories.  The default categories are things
+like _Classes_ and _Structures_ corresponding to programming-language concepts,
+as well as _Guides_ if `--documentation` is set.
+
+You can customize the categories and their contents using `custom_categories` in
+the config file — see the ReSwift [docs](https://reswift.github.io/ReSwift/) and
+[config file](https://github.com/ReSwift/ReSwift/blob/e94737282850fa038b625b4e351d1608a3d02cee/.jazzy.json)
+for an example.
+
+Within each category the items are ordered first alphabetically by source
+filename, and then by declaration order within the file.  You can use
+`// MARK:` comments within the file to create subheadings on the page, for
+example to split up properties and methods.  There’s no way to customize this
+order short of editing either the generated web page or the SourceKitten JSON.
+
+Swift extensions and Objective-C categories allow type members to be declared
+across multiple source files.  In general, extensions follow the main type
+declaration: first extensions from the same source file, then extensions from
+other files ordered alphabetically by filename.  Swift conditional extensions
+(`extension A where …`) always appear beneath unconditional extensions.
+
+Use this pattern to add or customize the subheading before extension members:
+```swift
+extension MyType {
+  // MARK: Subheading for this group of methods
+  …
+}
+```
+
+When Jazzy is using `--swift-build-tool symgraph` the source file names and
+line numbers may not be available. In this case the ordering is approximately
+alphabetical by symbol name and USR; the order is stable for the same input.
+
+Jazzy does not normally create separate web pages for declarations that do not
+have any members -- instead they are entirely nested into their parent page.  Use
+the `--separate-global-declarations` flag to change this and  create pages for
+these empty types.
 
 ### Choosing the Swift language version
 
 Jazzy normally uses the Swift compiler from the Xcode currently configured by
-`xcode-select`.  Use the `--swift-version` flag to compile with a different
-Xcode.
+`xcode-select`.  Use the `--swift-version` flag or the `DEVELOPER_DIR` environment
+variable to compile with a different Xcode.
 
 The value you pass to `--swift-version` must be the Swift language version given
-by `swift --version` in the Xcode you want to use.
+by `swift --version` in the Xcode you want to use. Jazzy uses
+[xcinvoke](https://github.com/segiddins/xcinvoke) to find a suitable Xcode
+installation on your system. This can be slow: if you know where Xcode is
+installed then it's faster to set `DEVELOPER_DIR` directly.
 
-For example to use Xcode 9.4:
+For example to use Xcode 14:
 ```shell
-jazzy --swift-version 4.1.2
+jazzy --swift-version 5.7
+```
+...or:
+```shell
+DEVELOPER_DIR=/Applications/Xcode_14.app/Contents/Developer jazzy
 ```
 
 ## Linux
@@ -423,6 +465,36 @@ Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
 
 See [this document](ObjectiveC.md).
 
+### Miscellaneous
+
+**Missing docset**
+
+Jazzy only builds a docset when you set the `--module` flag.
+
+**Unable to pass --build-tool-arguments containing commas**
+
+If you want Jazzy to run something like `xcodebuild -scheme Scheme -destination 'a=x,b=y,c=z'`
+then you must use the config file instead of the CLI flag because the CLI parser
+that Jazzy uses cannot handle arguments that themselves contain commas.
+
+The example config file here would be:
+```yaml
+build_tool_arguments:
+  - "-scheme"
+  - "Scheme"
+  - "-destination"
+  - "a=x,b=y,c=z"
+```
+
+**Errors running in an Xcode Run Script phase**
+
+Running Jazzy from an Xcode build phase can go wrong in cryptic ways when Jazzy
+has to run `xcodebuild`.
+
+Users [have reported](https://github.com/realm/jazzy/issues/1012) that error
+messages about symbols lacking USRs can be fixed by unsetting
+`LLVM_TARGET_TRIPLE_SUFFIX` as part of the run script.
+
 ### Installation Problems
 
 **Can't find header files / clang**

data/Rakefile

@@ -71,7 +71,7 @@ begin
       destination = "spec/integration_specs/#{source.gsub('tmp/', '')}/after"
       if File.exist?(destination)
         sh "rm -rf #{destination}"
-        sh "mv #{source} #{destination}"
+        sh "mv #{source}/transformed #{destination}"
       end
     end
 

data/jazzy.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'open4', '~> 1.3'
   spec.add_runtime_dependency 'redcarpet', '~> 3.4'
   spec.add_runtime_dependency 'rexml', '~> 3.2'
-  spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 4.0']
+  spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 5.0']
   spec.add_runtime_dependency 'sassc', '~> 2.1'
   spec.add_runtime_dependency 'sqlite3', '~> 1.3'
   spec.add_runtime_dependency 'xcinvoke', '~> 0.3.0'

data/js/package-lock.json

@@ -1,34 +1,51 @@
 {
-  "lockfileVersion": 2,
+  "name": "jazzy-js",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
   "requires": true,
   "packages": {
+    "": {
+      "name": "jazzy-js",
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "corejs-typeahead": "^1.3.1",
+        "jquery": "^3.7.1",
+        "katex": "^0.16.8",
+        "lunr": "^2.3.9"
+      }
+    },
     "node_modules/commander": {
-      "version": "6.2.1",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-6.2.1.tgz",
-      "integrity": "sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==",
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
       "engines": {
-        "node": ">= 6"
+        "node": ">= 12"
       }
     },
     "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==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.3.tgz",
+      "integrity": "sha512-i+WiSdYiB4QiWTlx9kbn/Nk3zvG/FT/cj8EgBlSkEvQB1doJKb61ix0i6jxe4Y8znvfM8g2nkSGglhsF/cWFAA==",
       "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=="
+      "version": "3.7.1",
+      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.7.1.tgz",
+      "integrity": "sha512-m4avr8yL8kmFN8psrbFFFmB/If14iN5o9nw/NgnnM+kybDJpRsAynV2BsfpTYrTRysYUdADVD7CkUUizgkpLfg=="
     },
     "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==",
+      "version": "0.16.8",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.8.tgz",
+      "integrity": "sha512-ftuDnJbcbOckGY11OO+zg3OofESlbR5DRl2cmN8HeWeeFIV7wTXvAOx8kEjZjobhA+9wh2fbKeO6cdcA9Mnovg==",
+      "funding": [
+        "https://opencollective.com/katex",
+        "https://github.com/sponsors/katex"
+      ],
       "dependencies": {
-        "commander": "^6.0.0"
+        "commander": "^8.3.0"
       },
       "bin": {
         "katex": "cli.js"
@@ -39,6 +56,5 @@
       "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
       "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
     }
-  },
-  "dependencies": {}
+  }
 }

data/js/package.json

@@ -10,8 +10,8 @@
   "license": "MIT",
   "dependencies": {
     "corejs-typeahead": "^1.3.1",
-    "jquery": "^3.6.0",
-    "katex": "^0.13.3",
+    "jquery": "^3.7.1",
+    "katex": "^0.16.8",
     "lunr": "^2.3.9"
   }
 }

data/lib/jazzy/config.rb

@@ -127,7 +127,7 @@ module Jazzy
     config_attr :clean,
       command_line: ['-c', '--[no-]clean'],
       description: ['Delete contents of output directory before running. ',
-                    'WARNING: If --output is set to ~/Desktop, this will '\
+                    'WARNING: If --output is set to ~/Desktop, this will ' \
                       'delete the ~/Desktop directory.'],
       default: false
 
@@ -201,7 +201,7 @@ module Jazzy
 
     config_attr :excluded_files,
       command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array],
-      description: 'Source file pathnames to be excluded from documentation. '\
+      description: 'Source file pathnames to be excluded from documentation. ' \
         'Supports wildcards.',
       default: [],
       parse: ->(files) do
@@ -210,7 +210,7 @@ module Jazzy
 
     config_attr :included_files,
       command_line: ['-i', '--include filepath1,filepath2,…filepathN', Array],
-      description: 'Source file pathnames to be included in documentation. '\
+      description: 'Source file pathnames to be included in documentation. ' \
         'Supports wildcards.',
       default: [],
       parse: ->(files) do
@@ -234,14 +234,14 @@ module Jazzy
 
     config_attr :swift_build_tool,
       command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
-      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 '\
+      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}, "\
+        raise "Unsupported swift_build_tool #{tool}, " \
           "supported values: #{SWIFT_BUILD_TOOLS.join(', ')}"
       end
 
@@ -265,13 +265,13 @@ module Jazzy
 
     config_attr :version,
       command_line: '--module-version VERSION',
-      description: 'Version string to use as part of the default docs '\
+      description: 'Version string to use as part of the default docs ' \
         'title and inside the docset.',
       default: '1.0'
 
     config_attr :title,
       command_line: '--title TITLE',
-      description: 'Title to display at the top of each page, overriding the '\
+      description: 'Title to display at the top of each page, overriding the ' \
         'default generated from module name and version.',
       default: ''
 
@@ -296,16 +296,16 @@ module Jazzy
 
     config_attr :podspec,
       command_line: '--podspec FILEPATH',
-      description: 'A CocoaPods Podspec that describes the Swift library to '\
+      description: 'A CocoaPods Podspec that describes the Swift library to ' \
         'document',
       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 '\
+      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: []
 
@@ -327,7 +327,7 @@ module Jazzy
 
     config_attr :dash_url,
       command_line: ['-d', '--dash_url URL'],
-      description: 'Location of the dash XML feed '\
+      description: 'Location of the dash XML feed ' \
         'e.g. https://realm.io/docsets/realm.xml)',
       parse: ->(d) { URI(d) }
 
@@ -342,7 +342,7 @@ module Jazzy
       parse: ->(host) do
         return host.to_sym if SOURCE_HOSTS.include?(host)
 
-        raise "Unsupported source_host '#{host}', "\
+        raise "Unsupported source_host '#{host}', " \
           "supported values: #{SOURCE_HOSTS.join(', ')}"
       end
 
@@ -359,7 +359,7 @@ module Jazzy
     config_attr :source_host_files_url,
       command_line: '--source-host-files-url PREFIX',
       description: [
-        "The base URL on the source host of the project's files, to link "\
+        "The base URL on the source host of the project's files, to link " \
           'from individual declarations.',
         'For example https://github.com/realm/realm-cocoa/tree/v0.87.1',
       ]
@@ -370,13 +370,13 @@ module Jazzy
 
     config_attr :docset_playground_url,
       command_line: '--docset-playground-url URL',
-      description: 'URL of an interactive playground to demonstrate the '\
+      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',
-      description: 'Avoid generating a search index. '\
+      description: 'Avoid generating a search index. ' \
         'Search is available in some themes.',
       default: false
 
@@ -387,7 +387,7 @@ module Jazzy
 
     config_attr :min_acl,
       command_line:
-         '--min-acl [private | fileprivate | internal | public | open]',
+         '--min-acl [private | fileprivate | internal | package | public | open]',
       description: 'minimum access control level to document',
       default: 'public',
       parse: ->(acl) do
@@ -396,7 +396,7 @@ module Jazzy
 
     config_attr :skip_undocumented,
       command_line: '--[no-]skip-undocumented',
-      description: "Don't document declarations that have no documentation "\
+      description: "Don't document declarations that have no documentation " \
         'comments.',
       default: false
 
@@ -406,21 +406,21 @@ module Jazzy
       default: false
 
     config_attr :custom_categories,
-      description: 'Custom navigation categories to replace the standard '\
-        "'Classes', 'Protocols', etc. Types not explicitly named "\
-        'in a custom category appear in generic groups at the '\
+      description: 'Custom navigation categories to replace the standard ' \
+        "'Classes', 'Protocols', etc. Types not explicitly named " \
+        'in a custom category appear in generic groups at the ' \
         'end.  Example: https://git.io/v4Bcp',
       default: []
 
     config_attr :custom_categories_unlisted_prefix,
-      description: "Prefix for navigation section names that aren't "\
+      description: "Prefix for navigation section names that aren't " \
         'explicitly listed in `custom_categories`.',
       default: 'Other '
 
     config_attr :hide_unlisted_documentation,
       command_line: '--[no-]hide-unlisted-documentation',
-      description: "Don't include documentation in the sidebar from the "\
-        "`documentation` config value that aren't explicitly "\
+      description: "Don't include documentation in the sidebar from the " \
+        "`documentation` config value that aren't explicitly " \
         'listed in `custom_categories`.',
       default: false
 
@@ -434,9 +434,9 @@ module Jazzy
 
     config_attr :theme_directory,
       command_line: "--theme [#{BUILTIN_THEMES.join(' | ')} | DIRPATH]",
-      description: "Which theme to use. Specify either 'apple' (default), "\
-        'one of the other built-in theme names, or the path to '\
-        'your mustache templates and other assets for a custom '\
+      description: "Which theme to use. Specify either 'apple' (default), " \
+        'one of the other built-in theme names, or the path to ' \
+        'your mustache templates and other assets for a custom ' \
         'theme.',
       default: 'apple',
       parse: ->(t) do
@@ -449,9 +449,9 @@ module Jazzy
 
     config_attr :use_safe_filenames,
       command_line: '--use-safe-filenames',
-      description: 'Replace unsafe characters in filenames with an encoded '\
-        'representation. This will reduce human readability of '\
-        'some URLs, but may be necessary for projects that '\
+      description: 'Replace unsafe characters in filenames with an encoded ' \
+        'representation. This will reduce human readability of ' \
+        'some URLs, but may be necessary for projects that ' \
         'expose filename-unfriendly functions such as /(_:_:)',
       default: false
 
@@ -471,20 +471,20 @@ module Jazzy
 
     config_attr :undocumented_text,
       command_line: '--undocumented-text UNDOCUMENTED_TEXT',
-      description: 'Default text for undocumented symbols. The default '\
+      description: 'Default text for undocumented symbols. The default ' \
         '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 "\
+      description: 'Create separate pages for all global declarations ' \
+        "(classes, structures, enums etc.) even if they don't " \
         'have children.',
       default: false
 
     config_attr :include_spi_declarations,
       command_line: '--[no-]include-spi-declarations',
-      description: 'Include Swift declarations marked `@_spi` even if '\
+      description: 'Include Swift declarations marked `@_spi` even if ' \
         '--min-acl is set to `public` or `open`.',
       default: false
 
@@ -594,14 +594,14 @@ module Jazzy
       if source_host_configured &&
          source_host_url.nil? &&
          source_host_files_url.nil?
-        warning 'Option `source_host` is set but has no effect without either '\
+        warning 'Option `source_host` is set but has no effect without either ' \
           '`source_host_url` or `source_host_files_url`.'
       end
 
       if objc_mode &&
          build_tool_arguments_configured &&
          (framework_root_configured || umbrella_header_configured)
-        warning 'Option `build_tool_arguments` is set: values passed to '\
+        warning 'Option `build_tool_arguments` is set: values passed to ' \
           '`framework_root` or `umbrella_header` may be ignored.'
       end
     end