{"id":29536765,"url":"https://github.com/heckj/example-docc-project","last_synced_at":"2025-07-17T03:09:31.639Z","repository":{"id":304408182,"uuid":"1018700360","full_name":"heckj/example-docc-project","owner":"heckj","description":"An example Swift package set up for hosting documentation","archived":false,"fork":false,"pushed_at":"2025-07-12T22:02:01.000Z","size":372,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-12T23:34:12.188Z","etag":null,"topics":["docc","example","swift"],"latest_commit_sha":null,"homepage":"https://heckj.github.io/example-docc-project/documentation/exampledocs/","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/heckj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-07-12T20:53:31.000Z","updated_at":"2025-07-12T22:02:05.000Z","dependencies_parsed_at":"2025-07-12T23:34:14.170Z","dependency_job_id":"d0b32f6b-f6ca-4080-8575-f05fd95f0520","html_url":"https://github.com/heckj/example-docc-project","commit_stats":null,"previous_names":["heckj/example-docc-project"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/heckj/example-docc-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heckj%2Fexample-docc-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heckj%2Fexample-docc-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heckj%2Fexample-docc-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heckj%2Fexample-docc-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heckj","download_url":"https://codeload.github.com/heckj/example-docc-project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heckj%2Fexample-docc-project/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265562378,"owners_count":23788517,"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":["docc","example","swift"],"created_at":"2025-07-17T03:09:30.966Z","updated_at":"2025-07-17T03:09:31.631Z","avatar_url":"https://github.com/heckj.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Example DocC Project\n\nAn example Swift package set up for hosting documentation.\n\nThe `Package.swift` exists to provide a target name and package structure around a DocC catalog that,\naside from Snippets, doesn't include any libraries, executables, or related API reference code.\n\nYou can edit and build the documentation content using Xcode, or from the command line.\n\n## Package Structure\n\nThis repository is structured to put the Documentation catalog at the root of the repository, which comes with some tradeoffs.\nThe `Package.swift` file is set up with a target that looks for sources in this directory, which means\nthat the swift compiler warns about files it doesn't know about.\nA couple of files (`LICENSE` and `README.md`) are explicitly excluded in the [package manifest](./Package.swift), but the `/docs` directory and its files - aren't included in that set.\nThe side effect of this is that everything builds normally, but you'll see warnings from the Swift compiler when invoking the documentation preview or builds.\n\nThe default structure for a Swift package would place the documentation catalog (the directory `Documentation.docc`) in the sources location based on the target.\nIn this example, that target is named `ExampleDocs` - so the default location is `Sources/ExampleDocs`.\nThe default structure is better for general usage - for example when you're provided API reference for a library or executable, or want to provide more than one catalog within the same repository.\n\n## Building Documentation\n\nTo build and preview the documentation from the command line:\n\n```bash\nswift package --disable-sandbox preview-documentation --target ExampleDocs\n```\n\nTo build the documentation for distribution, use the `generate-documentation` command:\n\n```bash\nswift package generate-documentation --target ExampleDocs\n```\n\n### Options\n\n- Use `--hosting-base-path` to specify the base path where you host the content. \n  For example, using public github pages, the base path is typically the repository name.\n  GitHub pages host at a virtual host based on the usename: `username.github.io`. \n  For this example, username: `heckj` and repository `example-docc-project`,\n    the base path option would be `--hosting-base-path example-docc-project`.\n\n- Use `--analyze --warnings-as-errors` to check on the status of the documentation content, which help identify broken links or missing content.\n\n- Use `--checkout-path`, `--source-service`, and `--source-service-base-url` to specify the source code service and base URL for the documentation to provide a link in the documentation content to the repository. \n  For this example, the options would be `--source-service github --source-service-base-url heckj/example-docc-project`\n  There may be an issue with using `--checkout-path` and related options with Swift 6.2 - [still debugging that](https://github.com/swiftlang/swift-docc/issues/1248).\n\n## Publishing Documentation\n\nAdd your package to [Swift Package Index](https://swiftpackageindex.com) to host the documentation and make it discoverable.\nYou can also build the documentation and host it on GitHub Pages or any other static hosting service.\nThis example project is set up to host the documentation on GitHub Pages, using the following command:\n\n```bash\nexport DOCC_JSON_PRETTYPRINT=YES # makes the output JSON easier to read, and diff\nswift package --disable-sandbox generate-documentation \\\n--target ExampleDocs \\\n--hosting-base-path example-docc-project \\\n--analyze --warnings-as-errors \\\n--output-path docs\n```\n\nThe GitHub pages configuration:\n\n![A screenshot of the GitHub pages configuration. Deploy from source, branch `main`, deploying from the directory `docs`.](img/github-pages-config.png)\n\nThe resulting pages are hosted at [heckj.github.io/example-docc-project](https://heckj.github.io/example-docc-project).\n\n\u003e ⚠️ Warning: DocC doesn't currently generate a link from the base directory to its content, so accessing the above URL \n\u003e results in \"Page not found\", even though the content IS hosted. Link to the content directly, in this case: [https://heckj.github.io/example-docc-project/documentation/exampledocs/](https://heckj.github.io/example-docc-project/documentation/exampledocs/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheckj%2Fexample-docc-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheckj%2Fexample-docc-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheckj%2Fexample-docc-project/lists"}