[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-7676":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":32,"discoverSource":33},7676,"jazzy","realm\u002Fjazzy","realm","Soulful docs for Swift & Objective-C","https:\u002F\u002Frealm.io",null,"Ruby",7385,414,155,72,0,2,38.85,"MIT License",false,"master",true,[24,25,26,27,28],"ruby","sourcekit","sourcekitten","swift","xcode","2026-06-12 02:01:43","![jazzy](images\u002Flogo.jpg)\n\n[![Build Status](https:\u002F\u002Fgithub.com\u002Frealm\u002Fjazzy\u002Factions\u002Fworkflows\u002FTests.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Frealm\u002Fjazzy\u002Factions\u002Fworkflows\u002FTests.yml)\n\n*jazzy is a command-line utility that generates documentation for Swift or Objective-C*\n\n## About\n\nBoth Swift and Objective-C projects are supported.\n\nInstead of parsing your source files, `jazzy` hooks into [Clang][clang] and\n[SourceKit][sourcekit] to use the [AST][ast] representation of your code and\nits comments for more accurate results. The output matches the look and feel\nof Apple’s official reference documentation, post WWDC 2014.\n\nJazzy can also generate documentation from compiled Swift modules [using their\nsymbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.\n\n![Screenshot](images\u002Fscreenshot.jpg)\n\nThis project adheres to the [Contributor Covenant Code of Conduct](https:\u002F\u002Frealm.io\u002Fconduct).\nBy participating, you are expected to uphold this code. Please report\nunacceptable behavior to [info@realm.io](mailto:info@realm.io).\n\n## Requirements\n\nYou need development tools to build the project you wish to document.  Jazzy supports\nboth [Xcode][xcode] and [Swift Package Manager][spm] projects.\n\nJazzy expects to be running on __macOS__.  See [below](#linux) for tips to run Jazzy\non Linux.\n\n## Installation\n\n```shell\n[sudo] gem install jazzy\n```\n\nSee [Installation Problems](#installation-problems) for solutions to some\ncommon problems.\n\n## Usage\n\nRun `jazzy` from your command line. Run `jazzy -h` for a list of additional options.\n\nIf your Swift module is the first thing to build, and it builds fine when running\n`xcodebuild` or `swift build` without any arguments from the root of your project, then\njust running `jazzy` (without any arguments) from the root of your project should\nsucceed too!\n\nIf Jazzy generates docs for the wrong module then use `--module` to tell it which\none you'd prefer.  If this doesn't help, and you're using Xcode, then try passing\nextra arguments to `xcodebuild`, for example\n`jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget`.\n\nIf you want to generate docs for several modules at once then see [Documenting multiple\nmodules](#documenting-multiple-modules).\n\nYou can set options for your project’s documentation in a configuration file,\n`.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of\nall available options, run `jazzy --help config`.\n\n### Supported documentation keywords\n\nSwift documentation is written in markdown and supports a number of special keywords.\nHere are some resources with tutorials and examples, starting with the most modern:\n* Apple's [Writing Symbol Documentation in Your Source Files](https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Fxcode\u002Fwriting-symbol-documentation-in-your-source-files) article.\n* Apple's [Formatting Your Documentation Content](https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Fxcode\u002Fformatting-your-documentation-content) article.\n* Apple's [Xcode Markup Formatting Reference](https:\u002F\u002Fdeveloper.apple.com\u002Flibrary\u002Fcontent\u002Fdocumentation\u002FXcode\u002FReference\u002Fxcode_markup_formatting_ref\u002F).\n* Erica Sadun's [Swift header documentation in Xcode 7](https:\u002F\u002Fericasadun.com\u002F2015\u002F06\u002F14\u002Fswift-header-documentation-in-xcode-7\u002F) post and her [book on Swift Documentation Markup](https:\u002F\u002Fitunes.apple.com\u002Fus\u002Fbook\u002Fswift-documentation-markup\u002Fid1049010423).\n\nFor Objective-C documentation the same keywords are supported, but note that the format\nis slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https:\u002F\u002Fdeveloper.apple.com\u002Flegacy\u002Flibrary\u002Fdocumentation\u002FDeveloperTools\u002FConceptual\u002FHeaderDoc\u002Ftags\u002Ftags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, @note, @code, @endcode, and @c.**\n\nJazzy can also generate cross-references within your documentation. A symbol name in\nbackticks generates a link, for example:\n* \\`MyClass\\` - a link to documentation for `MyClass`.\n* \\`MyClass.method(param1:)\\` - a link to documentation for that method.\n* \\`MyClass.method(...)\\` - shortcut syntax for the same thing.\n* \\`method(...)\\` - shortcut syntax to link to `method` from the documentation of another\n  method or property in the same class.\n* \\`[MyClass method1]\\` - a link to an Objective-C method.\n* \\`-[MyClass method2:param1]\\` - a link to another Objective-C method.\n\nJazzy understands Apple's DocC-style links too, for example:\n* \\`\\`MyClass\u002Fmethod(param1:)\\`\\` - a link to the documentation for that method\n  that appears as just `method(param1:)` in the rendered page.\n* \\`\\`\\\u003Cdoc:method(_:)-e873\\>\\`\\` - a link to a specific overload of `method(_:)`.\n  Jazzy can't tell which overload you intend and links to the first one.\n\nIf your documentation is for multiple modules then symbol name resolution works\napproximately as though all the modules have been imported: you can use \\`TypeName\\`\nto refer to a top-level type in any of the modules, or \\`ModuleName.TypeName\\` to\nbe specific.  If there is an ambiguity then you can use a leading slash to\nindicate that the first part of the name should be read as a module name:\n\\`\u002FModuleName.TypeName\\`.\n\n### Math\n\nJazzy can render math equations written in LaTeX embedded in your markdown:\n* `` `$equation$` `` renders the equation in an inline style.\n* `` `$$equation$$` `` renders the equation in a display style, centered on a\n  line of its own.\n\nFor example, the markdown:\n```markdown\nInline: `$ax^2+bx+c=0$`\n\nBlock: `$$x={\\frac {-b\\pm {\\sqrt {b^{2}-4ac}}}{2a}}$$`\n```\n..renders as:\n\n![math](images\u002Fmath.png)\n\nMath support is provided by [KaTeX](https:\u002F\u002Fkatex.org).\n\n### Swift\n\nSwift documentation is generated by default.\n\n##### Example\n\nThis is how Realm Swift docs are generated:\n\n```shell\njazzy \\\n  --clean \\\n  --author Realm \\\n  --author_url https:\u002F\u002Frealm.io \\\n  --source-host github \\\n  --source-host-url https:\u002F\u002Fgithub.com\u002Frealm\u002Frealm-cocoa \\\n  --source-host-files-url https:\u002F\u002Fgithub.com\u002Frealm\u002Frealm-cocoa\u002Ftree\u002Fv0.96.2 \\\n  --module-version 0.96.2 \\\n  --build-tool-arguments -scheme,RealmSwift \\\n  --module RealmSwift \\\n  --root-url https:\u002F\u002Frealm.io\u002Fdocs\u002Fswift\u002F0.96.2\u002Fapi\u002F \\\n  --output docs\u002Fswift_output \\\n  --theme docs\u002Fthemes\n```\n\nThis is how docs are generated for a project that uses the Swift Package Manager:\n\n```shell\njazzy \\\n  --module DeckOfPlayingCards \\\n  --swift-build-tool spm \\\n  --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5\n```\n\n### Objective-C\n\nTo generate documentation for a simple Objective-C project, you must pass the\nfollowing parameters:\n* `--objc`\n* `--umbrella-header ...`\n* `--framework-root ...`\n\n...and optionally:\n* `--sdk [iphone|watch|appletv][os|simulator]|macosx` (default value\n   of `macosx`)\n* `--hide-declarations [objc|swift]` (hides the selected language declarations)\n\nFor example, this is how the `AFNetworking` docs are generated:\n\n```shell\njazzy \\\n  --objc \\\n  --author AFNetworking \\\n  --author_url http:\u002F\u002Fafnetworking.com \\\n  --source-host github \\\n  --source-host-url https:\u002F\u002Fgithub.com\u002FAFNetworking\u002FAFNetworking \\\n  --source-host-files-url https:\u002F\u002Fgithub.com\u002FAFNetworking\u002FAFNetworking\u002Ftree\u002F2.6.2 \\\n  --module-version 2.6.2 \\\n  --umbrella-header AFNetworking\u002FAFNetworking.h \\\n  --framework-root . \\\n  --module AFNetworking\n```\n\nFor a more complicated Objective-C project, instead use `--build-tool-arguments`\nto pass arbitrary compiler flags.  For example, this is how Realm Objective-C\ndocs are generated:\n\n```shell\njazzy \\\n  --objc \\\n  --clean \\\n  --author Realm \\\n  --author_url https:\u002F\u002Frealm.io \\\n  --source-host github \\\n  --source-host-url https:\u002F\u002Fgithub.com\u002Frealm\u002Frealm-cocoa \\\n  --source-host-files-url https:\u002F\u002Fgithub.com\u002Frealm\u002Frealm-cocoa\u002Ftree\u002Fv2.2.0 \\\n  --module-version 2.2.0 \\\n  --build-tool-arguments --objc,Realm\u002FRealm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \\\n  --module Realm \\\n  --root-url https:\u002F\u002Frealm.io\u002Fdocs\u002Fobjc\u002F2.2.0\u002Fapi\u002F \\\n  --output docs\u002Fobjc_output \\\n  --head \"$(cat docs\u002Fcustom_head.html)\"\n```\n\nSee [the Objective-C docs](ObjectiveC.md) for more information and some tips\non troubleshooting.\n\n### Mixed Objective-C \u002F Swift\n\n*This feature has some rough edges.*\n\nTo generate documentation for a mixed Swift and Objective-C project you must first\ngenerate two [SourceKitten][sourcekitten] files: one for Swift and one for Objective-C.\n\nThen pass these files to Jazzy together using `--sourcekitten-sourcefile`.\n\n#### Example\n\nThis is how docs are generated from an Xcode project for a module containing both\nSwift and Objective-C files:\n\n```shell\n# Generate Swift SourceKitten output\nsourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme > swiftDoc.json\n\n# Generate Objective-C SourceKitten output\nsourcekitten doc --objc $(pwd)\u002FMyProject\u002FMyProject.h \\\n      -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \\\n      -I $(pwd) -fmodules > objcDoc.json\n\n# Feed both outputs to Jazzy as a comma-separated list\njazzy --module MyProject --sourcekitten-sourcefile swiftDoc.json,objcDoc.json\n```\n\n### Docs from `.swiftmodule`s or frameworks\n\nSwift 5.3 added support for symbol graph generation from `.swiftmodule` files.\n\nJazzy can use this to generate API documentation.  This is faster than using\nthe source code directly but does have limitations: for example documentation\ncomments are available only for `public` declarations, and the presentation of\nSwift extensions may not match the way they are written in code.\n\nSome examples:\n\n1. Generate docs for the Apple Combine framework for macOS:\n   ```shell\n   jazzy --module Combine --swift-build-tool symbolgraph\n   ```\n   The SDK's library directories are included in the search path by\n   default.\n2. Same but for iOS:\n   ```shell\n   jazzy --module Combine --swift-build-tool symbolgraph\n         --sdk iphoneos\n         --build-tool-arguments -target,arm64-apple-ios14.1\n   ```\n   The `target` is the LLVM target triple and needs to match the SDK.  The\n   default here is the target of the host system that Jazzy is running on,\n   something like `x86_64-apple-darwin19.6.0`.\n3. Generate docs for a personal `.swiftmodule`:\n   ```shell\n   jazzy --module MyMod --swift-build-tool symbolgraph\n         --build-tool-arguments -I,\u002FBuild\u002FProducts\n   ```\n   This implies that `\u002FBuild\u002FProducts\u002FMyMod.swiftmodule` exists.  Jazzy's\n   `--source-directory` (default current directory) is searched by default,\n   so you only need the `-I` override if that's not enough.\n4. For a personal framework:\n   ```shell\n   jazzy --module MyMod --swift-build-tool symbolgraph\n         --build-tool-arguments -F,\u002FBuild\u002FProducts\n   ```\n   This implies that `\u002FBuild\u002FProducts\u002FMyMod.framework` exists and contains\n   a `.swiftmodule`.  Again the `--source-directory` is searched by default\n   if `-F` is not passed in.\n5. With pre-generated symbolgraph files:\n    ```shell\n    jazzy --module MyMod --swift-build-tool symbolgraph\n          --symbolgraph-directory Build\u002Fsymbolgraphs\n    ```\n    If you've separately generated symbolgraph files by the use of \n    `-emit-symbol-graph`, you can pass the location of these files using\n    `--symbolgraph-directory` from where they can be parsed directly.\n\nSee `swift symbolgraph-extract -help` for all the things you can pass via\n`--build-tool-arguments`: if your module has dependencies then you may need\nto add various search path options to let Swift load it.\n\n### Documenting multiple modules\n\n*This feature is new, bugs and feedback welcome*\n\nSometimes it's useful to document multiple modules together in the same site,\nfor example an app and its extensions, or an SDK that happens to be implemented\nas several modules.\n\nJazzy can build docs for all these together and create a single site with\nsearch, cross-module linking, and navigation.\n\n#### Build configuration\n\nIf all the modules share the same build flags then the easiest way to do this\nis with `--modules`, for example `jazzy --modules ModuleA,ModuleB,ModuleC`.\n\nIf your modules have different build flags then you have to use the config file.\nFor example:\n```yaml\nmodules:\n  - module: ModuleA\n  - module: ModuleB\n    build_tool_arguments:\n      - -scheme\n      - SpecialScheme\n      - -target\n      - ModuleB\n    source_directory: ModuleBProject\n  - module: ModuleC\n    objc: true\n    umbrella_header: ModuleC\u002FModuleC.h\n    framework_root: ModuleC\n    sdk: appletvsimulator\n  - module: ModuleD\n    sourcekitten_sourcefile: [ModuleD1.json, ModuleD2.json]\n```\nThis describes a four-module project of which one is 'normal', one requires\nspecial Xcode treatment, one is Objective-C, and one has prebuilt SourceKitten\nJSON.\n\nPer-module options set at the top level are inherited by each module unless\nalso set locally -- but you can't set both `--module` and `--modules`.\n\nJazzy doesn't support `--podspec` mode in conjunction with the multiple\nmodules feature.\n\n#### Presentation\n\nThe `--merge-modules` flag controls how declarations from multiple modules\nare arranged into categories.\n\nThe default of `all` has Jazzy combine declarations from the modules so there\nis one category of classes, one of structures, and so on.  To the user this means\nthey do not worry about which module exports a particular type, although that\ninformation remains available in the type's page.\n\nSetting `--merge-modules none` changes this so each module is a top-level\ncategory, with the module's symbols listed under it.  \n\nSetting `--merge-modules extensions` is like `none` except cross-module\nextensions are shown as part of their extended type.  For example if `ModuleA`\nextends `ModuleB.SomeType` then those extension members from `ModuleA` are shown\non the `ModuleB.SomeType` page along with the rest of `SomeType`.\n\nYou can use `--documentation` to include guides, `custom_categories` to customize\nthe layout with types from whichever modules you want, and `--abstract` to add\nadditional markdown content to the per-module category pages.\n\nUse the `--title`, `--readme-title`, and `--docset-title` flags to control the\ntop-level names of your documentation.  Without these, Jazzy uses the name of one\nof the modules being documented.\n\n### Themes\n\nThree themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.\n\n* `apple` example: \u003Chttps:\u002F\u002Fjohnfairh.github.io\u002Fdemo-jazzy-apple-theme\u002F>\n* `fullwidth` example: \u003Chttps:\u002F\u002Freduxkit.github.io\u002FReduxKit\u002F>\n* `jony` example: \u003Chttps:\u002F\u002Fharshilshah.github.io\u002FIGListKit\u002F>\n\nYou can specify which theme to use by passing in the `--theme` option. You can\nalso provide your own custom theme by passing in the path to your theme\ndirectory.\n\n### Guides\n\n| Description | Command |\n| ---         | ---     |\n| Command line option | `--documentation={file pattern}` |\n| Example             | `--documentation=Docs\u002F*.md` |\n| jazzy.yaml example  | `documentation: Docs\u002F*.md` |\n\nBy default, jazzy looks for one of README.md, README.markdown, README.mdown or README (in that order) in the directory from where it runs to render the index page at the root of the docs output directory.\nUsing the `--documentation` option, extra markdown files can be integrated into the generated docs and sidebar navigation.\n\nAny files found matching the file pattern will be parsed and included as a document with the type 'Guide' when generated. If the files are not included using the `custom_categories` config option, they will be grouped under 'Other Guides' in the sidebar navigation.\n\nThere are a few limitations:\n- File names must be unique from source files.\n- Readme should be specified separately using the `readme` option.\n\nYou can link to a guide from other guides or doc comments using the name of the page\nas it appears in the site.  For example, to link to the guide generated from a file\ncalled `My Guide.md` you would write \\`My Guide\\`.\n\n### Section description abstracts\n\n| Description | Command |\n| ---         | ---     |\n| Command line option | `--abstract={file pattern}` |\n| Example             | `--abstract=Docs\u002FSections\u002F*.md` |\n| jazzy.yaml example  | `abstract: Docs\u002FSections\u002F*.md` |\n\nUsing the `--abstract` options, extra markdown can be included after the heading of section overview pages. Think of it as a template include.\n\nThe list of files matching the pattern is compared against the list of sections generated and if a match is found, it's contents will be included in that section before listing source output.\n\nUnlike the `--documentation` option, these files are not included in navigation and if a file does not match a section title, it is not included at all.\n\nThis is very helpful when using `custom_categories` for grouping types and including relevant documentation in those sections.\n\nFor an example of a project using both `--documentation` and `--abstract` see: [https:\u002F\u002Freswift.github.io\u002FReSwift\u002F](https:\u002F\u002Freswift.github.io\u002FReSwift\u002F)\n\n### Controlling what is documented\n\nIn Swift mode, Jazzy by default documents only `public` and `open` declarations. To\ninclude declarations with a lower access level, set the `--min-acl` flag to `internal`,\n`fileprivate`, or `private`.\n\nBy default, Jazzy does not document declarations marked `@_spi` when `--min-acl` is\nset to `public` or `open`.  Set the `--include-spi-declarations` flag to include them.\n\nIn Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header`\nheader file and any other header files included by it.\n\nYou can control exactly which declarations should be documented using `--exclude`,\n`--include`, or `:nodoc:`.\n\nThe `--include` and `--exclude` flags list source files that should be included\u002Fexcluded\nrespectively in the documentation. Entries in the list can be absolute pathnames beginning\nwith `\u002F` or relative pathnames. Relative pathnames are interpreted relative to the\ndirectory from where you run `jazzy` or, if the flags are set in the config file, relative\nto the directory containing the config file. Entries in the list can match multiple files\nusing `*` to match any number of characters including `\u002F`.  For example:\n* `jazzy --include=\u002FUsers\u002Ffred\u002Fproject\u002FSources\u002FSecret.swift` -- include a specific file\n* `jazzy --exclude=\u002F*\u002FInternal*` -- exclude all files with names that begin with *Internal*\n  and any files under any directory with a name beginning *Internal*.\n* `jazzy --exclude=Impl1\u002F*,Impl2\u002F*` -- exclude all files under the directories *Impl1* and\n  *Impl2* found in the current directory.\n\nNote that the `--include` option is applied before the `--exclude` option. For example:\n\n* `jazzy --include=\u002F*\u002FInternal* --exclude=Impl1\u002F*,Impl2\u002F*` -- include all files with names\n  that begin with *Internal* and any files under any directory with a name beginning\n  *Internal*, **except** for those under the directories *Impl1* and *Impl2* found in the\n  current directory\n\nDeclarations with a documentation comment containing `:nodoc:` are excluded from the\ndocumentation.\n\nDeclarations with the `@_documentation(visibility:)` attribute are treated as though they\nare written with the given visibility.  You can use this as a replacement for `:nodoc:` as\npart of a transition to Apple's DocC but it is not compatible with Jazzy's symbolgraph mode.\n\n### Documentation structure\n\nJazzy arranges documentation into categories.  The default categories are things\nlike _Classes_ and _Structures_ corresponding to programming-language concepts,\nas well as _Guides_ if `--documentation` is set.\n\nYou can customize the categories and their contents using `custom_categories` in\nthe config file. `custom_categories` is an array of objects.  Each category must contain two properties:\n- `name`: A string with the name you want to give to this category\n- `children`: An array used to specify the root level declarations that you want to add to\nthis category. \n\nEach child, then, can be one of the following:\n- A string, containing either the exact name of one root level declaration you want to\nmatch, or the fully qualified name (`ModuleName.DeclarationName`)\n- An object, containing the property:\n  - `regex`: a string which will be used to match multiple root level declarations from\nall of the modules.\n\nSee the ReSwift [docs](https:\u002F\u002Freswift.github.io\u002FReSwift\u002F) and\n[config file](https:\u002F\u002Fgithub.com\u002FReSwift\u002FReSwift\u002Fblob\u002Fe94737282850fa038b625b4e351d1608a3d02cee\u002F.jazzy.json)\nfor an example.\n\nWithin each category the items are ordered first alphabetically by source\nfilename, and then by declaration order within the file.  You can use\n`\u002F\u002F MARK:` comments within the file to create subheadings on the page, for\nexample to split up properties and methods.  There’s no way to customize this\norder short of editing either the generated web page or the SourceKitten JSON.\n\nSwift extensions and Objective-C categories allow type members to be declared\nacross multiple source files.  In general, extensions follow the main type\ndeclaration: first extensions from the same source file, then extensions from\nother files ordered alphabetically by filename.  Swift conditional extensions\n(`extension A where …`) always appear beneath unconditional extensions.\n\nUse this pattern to add or customize the subheading before extension members:\n```swift\nextension MyType {\n  \u002F\u002F MARK: Subheading for this group of methods\n  …\n}\n```\n\nWhen Jazzy is using `--swift-build-tool symgraph` the source file names and\nline numbers may not be available. In this case the ordering is approximately\nalphabetical by symbol name and USR; the order is stable for the same input.\n\nJazzy does not normally create separate web pages for declarations that do not\nhave any members -- instead they are entirely nested into their parent page.  Use\nthe `--separate-global-declarations` flag to change this and create pages for\nthese empty types.\n\n### Choosing the Swift language version\n\nJazzy normally uses the Swift compiler from the Xcode currently configured by\n`xcode-select`.  Use the `--swift-version` flag or the `DEVELOPER_DIR` environment\nvariable to compile with a different Xcode.\n\nThe value you pass to `--swift-version` must be the Swift language version given\nby `swift --version` in the Xcode you want to use. Jazzy uses\n[xcinvoke](https:\u002F\u002Fgithub.com\u002Fsegiddins\u002Fxcinvoke) to find a suitable Xcode\ninstallation on your system. This can be slow: if you know where Xcode is\ninstalled then it's faster to set `DEVELOPER_DIR` directly.\n\nFor example to use Xcode 14:\n```shell\njazzy --swift-version 5.7\n```\n...or:\n```shell\nDEVELOPER_DIR=\u002FApplications\u002FXcode_14.app\u002FContents\u002FDeveloper jazzy\n```\n\n### Dash Docset Support\n\nAs well as the browsable HTML documentation, Jazzy creates a _docset_ for use\nwith the [Dash][dash] app.\n\nBy default the docset is created at `docs\u002Fdocsets\u002FModuleName.tgz`.  Use\n`--docset-path` to create it somewhere else; use `--docset-title` to change\nthe docset's title.\n\nUse `--docset-playground-url` and `--docset-icon` to further customize the\ndocset.\n\nIf you set both `--root-url` to be the (https:\u002F\u002F) URL where you plan to deploy\nyour documentation and `--version` to give your documentation a version number\nthen Jazzy also creates a docset feed XML file and includes an \"Install in Dash\"\nbutton on the site.  This lets users who are browsing your documentation on the\nweb install and start using the docs in Dash locally.\n\n## Linux\n\nJazzy uses [SourceKitten][sourcekitten] to communicate with the Swift build\nenvironment and compiler.  The `sourcekitten` binary included in the Jazzy gem\nis built for macOS and so does not run on other operating systems.\n\nTo use Jazzy on Linux you first need to install and build `sourcekitten`\nfollowing instructions from [SourceKitten's GitHub repository][sourcekitten].\n\nThen to generate documentation for a SwiftPM project, instead of running just\n`jazzy` do:\n```shell\nsourcekitten doc --spm > doc.json\njazzy --sourcekitten-sourcefile doc.json\n```\n\nWe hope to improve this process in the future.\n\n## Troubleshooting\n\n### Swift\n\n**Only extensions are listed in the documentation?**\n\nCheck the `--min-acl` setting -- see [above](#controlling-what-is-documented).\n\n**Unable to find an Xcode with swift version X**\n\n1. The value passed with `--swift-version` must exactly match the version\n   number from `swiftc --version`.  For example Xcode 10.1 needs\n   `--swift-version 4.2.1`.  See [the flag documentation](#choosing-the-swift-language-version).\n2. The Xcode you want to use must be in the Spotlight index.  You can check\n   this using `mdfind 'kMDItemCFBundleIdentifier == com.apple.dt.Xcode'`.\n   Some users have reported this issue being fixed by a reboot; `mdutil -E`\n   may also help.  If none of these work then you can set the `DEVELOPER_DIR`\n   environment variable to point to the Xcode you want before running Jazzy\n   without the `--swift-version` flag.\n\n### Objective-C\n\nSee [this document](ObjectiveC.md).\n\n### Miscellaneous\n\n**Missing docset**\n\nJazzy only builds a docset when you set the `--module` or `--modules` flag.\n\n**Unable to pass --build-tool-arguments containing commas**\n\nIf you want Jazzy to run something like `xcodebuild -scheme Scheme -destination 'a=x,b=y,c=z'`\nthen you must use the config file instead of the CLI flag because the CLI parser\nthat Jazzy uses cannot handle arguments that themselves contain commas.\n\nThe example config file here would be:\n```yaml\nbuild_tool_arguments:\n  - \"-scheme\"\n  - \"Scheme\"\n  - \"-destination\"\n  - \"a=x,b=y,c=z\"\n```\n\n**Errors running in an Xcode Run Script phase**\n\nRunning Jazzy from an Xcode build phase can go wrong in cryptic ways when Jazzy\nhas to run `xcodebuild`.\n\nUsers [have reported](https:\u002F\u002Fgithub.com\u002Frealm\u002Fjazzy\u002Fissues\u002F1012) that error\nmessages about symbols lacking USRs can be fixed by unsetting\n`LLVM_TARGET_TRIPLE_SUFFIX` as part of the run script.\n\n**Warnings about matches and leftovers when using globs and wildcards**\n\nSome flags such as `--include` and `--documentation` support '*' characters as\nwildcards.  If you are using the CLI then you must make sure that your shell\ndoes not itself try to interpret them, for example by quoting the token: use\n`jazzy --documentation '*.md'` instead of `jazzy --documentation *.md`.\n\n### Installation Problems\n\n**Can't find header files \u002F clang**\n\nSome of the Ruby gems that Jazzy depends on have native C extensions.  This\nmeans you need the Xcode command-line developer tools installed to build\nthem: run `xcode-select --install` to install the tools.\n\n**\u002FApplications\u002FXcode: No such file or directory**\n\nThe path of your active Xcode installation must not contain spaces.  So\n`\u002FApplications\u002FXcode.app\u002F` is fine, `\u002FApplications\u002FXcode-10.2.app\u002F` is fine,\nbut `\u002FApplications\u002FXcode 10.2.app\u002F` is not.  This restriction applies only\nwhen *installing* Jazzy, not running it.\n\n### MacOS Before 10.14.4\n\nStarting with Jazzy 0.10.0, if you see an error similar to `dyld: Symbol not found: _$s11SubSequenceSlTl` then you need to install the [Swift 5 Runtime Support for Command Line Tools](https:\u002F\u002Fsupport.apple.com\u002Fkb\u002FDL1998).\n\nAlternatively, you can:\n* Update to macOS 10.14.4 or later; or\n* Install Xcode 10.2 or later at `\u002FApplications\u002FXcode.app`.\n\n## Development\n\nPlease review jazzy's [contributing guidelines](https:\u002F\u002Fgithub.com\u002Frealm\u002Fjazzy\u002Fblob\u002Fmaster\u002FCONTRIBUTING.md) when submitting pull requests.\n\njazzy is composed of two parts:\n\n1. The parser, [SourceKitten][SourceKitten] (written in Swift)\n2. The site generator (written in ruby)\n\nTo build and run jazzy from source:\n\n1. Install [bundler][bundler].\n2. Run `bundle install` from the root of this repo.\n3. Run jazzy from source by running `bin\u002Fjazzy`.\n\nInstructions to build SourceKitten from source can be found at\n[SourceKitten's GitHub repository][SourceKitten].\n\n## Design Goals\n\n- Generate source code docs matching Apple's official reference documentation\n- Support for standard Objective-C and Swift documentation comment syntax\n- Leverage modern HTML templating ([Mustache][mustache])\n- Leverage the power and accuracy of the [Clang AST][ast] and [SourceKit][sourcekit]\n- Support for Dash docsets\n- Support Swift and Objective-C\n\n## License\n\nThis project is released under the [MIT license](https:\u002F\u002Fgithub.com\u002Frealm\u002Fjazzy\u002Fblob\u002Fmaster\u002FLICENSE).\n\n## About\n\n\u003Cimg src=\"images\u002Frealm.png\" width=\"184\" \u002F>\n\nJazzy is maintained and funded by Realm Inc. The names and logos for\nRealm are trademarks of Realm Inc.\n\nWe :heart: open source software!\nSee [our other open source projects](https:\u002F\u002Fgithub.com\u002Frealm),\nread [our blog](https:\u002F\u002Frealm.io\u002Fnews) or say hi on twitter\n([@realm](https:\u002F\u002Ftwitter.com\u002Frealm)).\n\n[clang]: https:\u002F\u002Fclang.llvm.org \"Clang\"\n[sourcekit]: https:\u002F\u002Fwww.jpsim.com\u002Funcovering-sourcekit \"Uncovering SourceKit\"\n[ast]: https:\u002F\u002Fclang.llvm.org\u002Fdocs\u002FIntroductionToTheClangAST.html \"Introduction To The Clang AST\"\n[xcode]: https:\u002F\u002Fdeveloper.apple.com\u002Fxcode \"Xcode\"\n[SourceKitten]: https:\u002F\u002Fgithub.com\u002Fjpsim\u002FSourceKitten \"SourceKitten\"\n[bundler]: https:\u002F\u002Frubygems.org\u002Fgems\u002Fbundler\n[mustache]: https:\u002F\u002Fmustache.github.io \"Mustache\"\n[spm]: https:\u002F\u002Fswift.org\u002Fpackage-manager\u002F \"Swift Package Manager\"\n[dash]: https:\u002F\u002Fkapeli.com\u002Fdash\u002F \"Dash\"\n","jazzy 是一个命令行工具，用于生成 Swift 或 Objective-C 项目的文档。它通过接入 Clang 和 SourceKit 来使用代码及其注释的抽象语法树 (AST) 表示，从而提供更准确的结果。生成的文档样式与苹果官方参考文档一致，支持从源代码或已编译的 Swift 模块中提取符号图来生成文档。适用于 macOS 环境下需要高质量文档输出的 Swift 或 Objective-C 开发项目，尤其适合那些希望文档风格与苹果官方文档保持一致的开发者。","2026-06-11 03:13:42","top_language"]