{"id":13496272,"url":"https://github.com/SwiftDocOrg/swift-doc","last_synced_at":"2025-03-28T18:31:46.667Z","repository":{"id":41458630,"uuid":"236502369","full_name":"SwiftDocOrg/swift-doc","owner":"SwiftDocOrg","description":"A documentation generator for Swift projects","archived":true,"fork":false,"pushed_at":"2023-06-01T03:58:47.000Z","size":1434,"stargazers_count":1689,"open_issues_count":66,"forks_count":98,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-03-10T16:40:08.701Z","etag":null,"topics":["documentation-generator","swift"],"latest_commit_sha":null,"homepage":"https://swiftdoc.org","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SwiftDocOrg.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-27T13:58:15.000Z","updated_at":"2025-03-07T22:32:58.000Z","dependencies_parsed_at":"2024-06-18T12:32:36.671Z","dependency_job_id":"83ec36a2-fdc5-4a0a-8420-2a191350b487","html_url":"https://github.com/SwiftDocOrg/swift-doc","commit_stats":{"total_commits":283,"total_committers":27,"mean_commits":"10.481481481481481","dds":0.3180212014134276,"last_synced_commit":"f935ebfe524a0ff27bda07dadc3662e3e45b5125"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2Fswift-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2Fswift-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2Fswift-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwiftDocOrg%2Fswift-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SwiftDocOrg","download_url":"https://codeload.github.com/SwiftDocOrg/swift-doc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246080634,"owners_count":20720562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation-generator","swift"],"created_at":"2024-07-31T19:01:44.888Z","updated_at":"2025-03-28T18:31:46.092Z","avatar_url":"https://github.com/SwiftDocOrg.png","language":"Swift","funding_links":[],"categories":["Swift","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# swift-doc\n\n![CI][ci badge]\n\nA package for generating documentation for Swift projects.\n\nGiven a directory of Swift files,\n`swift-doc` generates HTML or CommonMark (Markdown) files\nfor each class, structure, enumeration, and protocol\nas well as top-level type aliases, functions, and variables.\n\n**Example Output**\n\n- [HTML][swiftsemantics html]\n- [CommonMark / GitHub Wiki][alamofire wiki]\n\n## Requirements\n\n- Swift 5.3+\n- [libxml2][libxml2]\n- [GraphViz][graphviz] _(optional)_\n\n## Command-Line Utility\n\n`swift-doc` can be used from the command-line on macOS and Linux.\n\n### Installation\n\n#### Homebrew\n\nRun the following command to install using [Homebrew](https://brew.sh/):\n\n```console\n$ brew install swiftdocorg/formulae/swift-doc\n```\n\nIf you already have `swift-doc` installed,\nrun the following command to upgrade your installation:\n\n```console\n$ brew upgrade swift-doc\n```\n\nIf installing or upgrading fails with the message\n*Error: Failed to download resource \"swift-doc\"*,\ntry resetting your installation with the following commands:\n\n```console\n$ brew uninstall swift-doc\n$ brew untap swiftdocorg/formulae\n$ brew install swiftdocorg/formulae/swift-doc\n```\n\n#### Docker\n\nYou can run `swift-doc` from the latest [Docker][docker] image\nwith the following commands:\n\n```terminal\n$ docker pull swiftdoc/swift-doc:latest\n$ docker run -it swiftdoc/swift-doc\n```\n\n#### Manually\n\nRun the following commands to build and install manually:\n\n```terminal\n$ git clone https://github.com/SwiftDocOrg/swift-doc\n$ cd swift-doc\n$ make install\n```\n\nIf you're on Ubuntu Linux,\nyou may need to first install the prerequisites\nby running the following command:\n\n```terminal\n$ apt-get update\n$ apt-get install -y libxml2-dev graphviz\n```\n\n### Usage\n\n    OVERVIEW: A utility for generating documentation for Swift code.\n    \n    USAGE: swift doc \u003csubcommand\u003e\n    \n    OPTIONS:\n      --version               Show the version.\n      -h, --help              Show help information.\n    \n    SUBCOMMANDS:\n      generate                Generates Swift documentation\n      coverage                Generates documentation coverage statistics for Swift\n                              files\n      diagram                 Generates diagram of Swift symbol relationships\n\n\u003e **Note**:\n\u003e The `swift` driver provides extensibility through subcommands.\n\u003e If you type an unknown subcommand like `swift foo`,\n\u003e the system looks for a command called `swift-foo` in your `PATH`.\n\u003e This mechanism allows `swift-doc` to be run either directly or as `swift doc`.\n\n#### swift-doc generate\n\n    OVERVIEW: Generates Swift documentation\n\n    USAGE: swift doc generate [\u003cinputs\u003e ...] --module-name \u003cmodule-name\u003e [--output \u003coutput\u003e] [--format \u003cformat\u003e] [--base-url \u003cbase-url\u003e]\n\n    ARGUMENTS:\n      \u003cinputs\u003e                One or more paths to a directory containing Swift files. \n\n    OPTIONS:\n      -n, --module-name \u003cmodule-name\u003e\n                              The name of the module \n      -o, --output \u003coutput\u003e   The path for generated output (default:\n                              .build/documentation)\n      -f, --format \u003cformat\u003e   The output format (default: commonmark)\n      --base-url \u003cbase-url\u003e   The base URL used for all relative URLs in generated\n                              documents. (default: /)\n      --minimum-access-level \u003cminimum-access-level\u003e\n                              The minimum access level of the symbols which should\n                              be included. (default: public)\n      -h, --help              Show help information.\n\nThe `generate` subcommand\ntakes one or more paths and enumerates them recursively,\ncollecting all Swift files into a single \"module\"\nand generating documentation accordingly.\nAny hidden directories are skipped,\nincluding `.git` and other directories with paths starting with a dot (`.`).\nTop-level `Tests` directories are skipped as well.\n\n```terminal\n$ swift doc generate path/to/SwiftProject --module-name SwiftProject\n$ tree .build/documentation\n$ documentation/\n├── Home\n├── (...)\n├── _Footer.md\n└── _Sidebar.md\n```\n\nBy default,\noutput files are written to `.build/documentation`\nin CommonMark / GitHub Wiki format,\nbut you can change that with the `--output` and `--format` option flags.\n\n```terminal\n$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject --output Documentation --format html\n$ Documentation/\n├── (...)\n└── index.html\n```\n\nBy default,\n`swift-doc` includes only symbols declared as `public` or `open`\nin the generated documentation.\nTo include `internal` or `private` declarations,\npass the `--minimum-access-level` flag with the specified access level.\n\n#### swift-doc coverage\n\n    OVERVIEW: Generates documentation coverage statistics for Swift files\n\n    USAGE: swift doc coverage [\u003cinputs\u003e ...] [--output \u003coutput\u003e]\n\n    ARGUMENTS:\n      \u003cinputs\u003e                One or more paths to a directory containing Swift files.\n\n    OPTIONS:\n      -o, --output \u003coutput\u003e   The path for generated report \n      --minimum-access-level \u003cminimum-access-level\u003e\n                              The minimum access level of the symbols which should\n                              be included. (default: public)\n      -h, --help              Show help information.\n\nThe `coverage` subcommand\ngenerates documentation coverage statistics for Swift files.\n\n```terminal\n$ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git\n\n$ swift run swift-doc coverage SwiftSemantics/Sources --output \"dcov.json\"\n$ cat dcov.json | jq \".data.totals\"\n{\n  \"count\": 207,\n  \"documented\": 199,\n  \"percent\": 96.1352657004831\n}\n\n$ cat dcov.json | jq \".data.symbols[] | select(.documented == false)\"\n{\n  \"file\": \"SwiftSemantics/Supporting Types/GenericRequirement.swift\",\n  \"line\": 67,\n  \"column\": 6,\n  \"name\": \"GenericRequirement.init?(_:)\",\n  \"type\": \"Initializer\",\n  \"documented\": false\n}\n...\n```\n\nWhile there are plenty of tools for assessing test coverage for code,\nwe weren't able to find anything analogous for documentation coverage.\nTo this end,\nwe've contrived a simple JSON format\n[inspired by llvm-cov](https://reviews.llvm.org/D22651#change-xdePaVfBugps).\n\nIf you know of an existing standard\nthat you think might be better suited for this purpose,\nplease reach out by [opening an Issue][open an issue]!\n\n#### swift-doc diagram\n\n    OVERVIEW: Generates diagram of Swift symbol relationships\n\n    USAGE: swift doc diagram [\u003cinputs\u003e ...]\n\n    ARGUMENTS:\n      \u003cinputs\u003e                One or more paths to a directory containing Swift files.\n\n    OPTIONS:\n      --minimum-access-level \u003cminimum-access-level\u003e\n                              The minimum access level of the symbols which should\n                              be included. (default: public)\n      -h, --help              Show help information.\n\nThe `diagram` subcommand\ngenerates a graph of APIs in [DOT format][dot]\nthat can be rendered by [GraphViz][graphviz] into a diagram.\n\n```terminal\n$ swift run swift-doc diagram Alamofire/Source \u003e Alamofire.gv\n$ head Alamofire.gv\ndigraph Anonymous {\n  \"Session\" [shape=box];\n  \"NetworkReachabilityManager\" [shape=box];\n  \"URLEncodedFormEncoder\" [shape=box,peripheries=2];\n  \"ServerTrustManager\" [shape=box];\n  \"MultipartFormData\" [shape=box];\n\n  subgraph cluster_Request {\n    \"DataRequest\" [shape=box];\n    \"Request\" [shape=box];\n\n$ dot -T svg Alamofire.gv \u003e Alamofire.svg\n```\n\nHere's an excerpt of the graph generated for Alamofire:\n\n![Excerpt of swift-doc-api Diagram for Alamofire](https://user-images.githubusercontent.com/7659/73189318-0db0e880-40d9-11ea-8895-341a75ce873c.png)\n\n## GitHub Action\n\nThis repository also hosts a [GitHub Action][github actions]\nthat you can incorporate into your project's workflow.\n\nThe CommonMark files generated by `swift-doc`\nare formatted for publication to your project's [GitHub Wiki][github wiki],\nwhich you can do with\n[github-wiki-publish-action][github-wiki-publish-action].\nAlternatively,\nyou could specify HTML format to publish documentation to\n[GitHub Pages](https://pages.github.com)\nor bundle them into a release artifact.\n\n### Inputs\n\n- `inputs`:\n  A path to a directory containing Swift (`.swift`) files in your workspace.\n  (Default: `\"./Sources\"`)\n- `format`:\n  The output format (`\"commonmark\"` or `\"html\"`)\n  (Default: `\"commonmark\"`)\n- `module-name`:\n  The name of the module.\n- `base-url`:\n  The base URL for all relative URLs generated in documents.\n  (Default: `\"/\"`)\n- `output`:\n  The path for generated output.\n  (Default: `\"./.build/documentation\"`)\n\n### Example Workflow\n\n```yml\n# .github/workflows/documentation.yml\nname: Documentation\n\non: [push]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v1\n      - name: Generate Documentation\n        uses: SwiftDocOrg/swift-doc@master\n        with:\n          inputs: \"Sources\"\n          module-name: MyLibrary\n          output: \"Documentation\"\n      - name: Upload Documentation to Wiki\n        uses: SwiftDocOrg/github-wiki-publish-action@v1\n        with:\n          path: \"Documentation\"\n        env:\n          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}\n```\n\n## Development\n\n### Web Assets\n\nCSS assets used by the HTML output format\nare processed and generated by [PostCSS](https://postcss.org).\nTo make changes to these assets,\nyou'll need to have [Node.js](https://nodejs.org/en/)\nand a package manager, such as [`npm`](https://www.npmjs.com),\ninstalled on your machine.\n\nNavigate to the `.node` directory\nand run `npm install` to download the required tools and libraries.\n\n```terminal\n$ cd .node\n$ npm install\n```\n\n\u003e **Note**:\n\u003e `package.json` is located at a hidden `.node` subdirectory\n\u003e to prevent Xcode from displaying or indexing the contents of `node_modules`\n\u003e when opening the main project.\n\nFrom the `.node` directory,\nrun the `watch` script\nto start watching for changes to files in the `Assets` folder.\nWhenever an asset source file is added, removed, or updated,\nits corresponding (unoptimized) product is automatically generated\nin the `Sources/swift-doc/Generated` folder.\n\n```terminal\n$ npm run watch\n```\n\nWhen you're happy with the results,\ncommit any changes to the source files in `Assets`\nas well as the generated files in `Sources/swift-doc/Generated`.\n\n```terminal\n$ git add Assets Sources/swift-doc/Generated\n$ git commit\n```\n\n## Release Process\n\n\u003e The following information is primarily for the benefit of project maintainers.\n\u003e That said, if you have any suggestions for how to improve this process,\n\u003e please let us know by [opening an issue][open an issue].\n\nFollow these steps to release a new version of `swift-doc`:\n\n- [x] Verify that the latest commit\n      [passed all CI checks](https://github.com/SwiftDocOrg/swift-doc/actions?query=workflow%3ACI).\n- [x] Update the Changelog by creating a new heading for the release\n      and modifying the last path component for the `unreleased` link reference.\n- [x] Update the [`version` constant](https://github.com/SwiftDocOrg/swift-doc/blob/master/Sources/swift-doc/main.swift#L25)\n      in the command-line executable.\n- [x] Create a new commit with the message \"Bump version to `$VERSION`\",\n      where `$VERSION` is a [SemVer]-compatible version number.\n- [x] Tag that commit with the tag name \"`$VERSION`\"\n- [x] Run the command `git push origin master --tags`\n- [x] Create a new [release](https://github.com/SwiftDocOrg/swift-doc/releases)\n      that corresponds to the new tag.\n\n## Known Issues\n\n- Xcode cannot run unit tests (\u003ckbd\u003e⌘\u003c/kbd\u003e\u003ckbd\u003eU\u003c/kbd\u003e)\n  when opening the swift-doc package directly,\n  as opposed first to generating an Xcode project file with\n  `swift package generate-xcodeproj`.\n  (The reported error is:\n  `Library not loaded: @rpath/lib_InternalSwiftSyntaxParser.dylib`).\n  As a workaround,\n  you can [install the latest toolchain](https://swift.org/download/)\n  and enable it in \"Xcode \u003e Preferences \u003e Components \u003e Toolchains\".\n  Alternatively,\n  you can run unit tests from the command line\n  with `swift test`.\n\n## License\n\nMIT\n\n## Contact\n\nMattt ([@mattt](https://twitter.com/mattt))\n\n[ci badge]: https://github.com/SwiftDocOrg/swift-doc/workflows/CI/badge.svg\n[alamofire wiki]: https://github.com/SwiftDocOrg/Alamofire/wiki\n[swiftsemantics html]: https://swift-doc-preview.netlify.app\n[github wiki]: https://help.github.com/en/github/building-a-strong-community/about-wikis\n[github actions]: https://github.com/features/actions\n[swiftsyntax]: https://github.com/apple/swift-syntax\n[swiftsemantics]: https://github.com/SwiftDocOrg/SwiftSemantics\n[swiftmarkup]: https://github.com/SwiftDocOrg/SwiftMarkup\n[commonmark]: https://github.com/SwiftDocOrg/CommonMark\n[github-wiki-publish-action]: https://github.com/SwiftDocOrg/github-wiki-publish-action\n[open an issue]: https://github.com/SwiftDocOrg/swift-doc/issues/new\n[jazzy]: https://github.com/realm/jazzy\n[swift number protocols diagram]: https://nshipster.com/propertywrapper/#swift-number-protocols\n[protocol-oriented programming]: https://asciiwwdc.com/2015/sessions/408\n[apple documentation]: https://developer.apple.com/documentation\n[se-0195]: https://github.com/apple/swift-evolution/blob/master/proposals/0195-dynamic-member-lookup.md\n[se-o258]: https://github.com/apple/swift-evolution/blob/master/proposals/0258-property-wrappers.md\n[se-xxxx]: https://github.com/apple/swift-evolution/blob/9992cf3c11c2d5e0ea20bee98657d93902d5b174/proposals/XXXX-function-builders.md\n[swiftdoc.org]: https://swiftdoc.org\n[jazzy swiftsemantics]: https://swift-semantics-jazzy.netlify.com\n[swift-doc swiftsemantics]: https://github.com/SwiftDocOrg/SwiftSemantics/wiki\n[@natecook1000]: https://github.com/natecook1000\n[nshipster]: https://nshipster.com\n[dependency hell]: https://github.com/apple/swift-package-manager/tree/master/Documentation#dependency-hell\n[pcre]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions\n[dot]: https://en.wikipedia.org/wiki/DOT_(graph_description_language)\n[graphviz]: https://www.graphviz.org\n[libxml2]: https://en.wikipedia.org/wiki/Libxml2\n[docker]: https://www.docker.com\n[semver]: https://semver.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSwiftDocOrg%2Fswift-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSwiftDocOrg%2Fswift-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSwiftDocOrg%2Fswift-doc/lists"}