swift-evolution Documentation

1. Project Overview & Quickstart (swiftlang/swift-evolution) Copy Chapter

Swift Evolution

https://www.swift.org/swift-evolution/

This repository tracks the ongoing evolution of the Swift programming language, standard library, and package manager.

Goals and Release Notes Copy Chapter

• Swift Language focus areas heading into 2025
• CHANGELOG

2. Official Technical Reference & Guides (swiftlang/docs) Copy Chapter

File: README.md Copy Chapter

Welcome to the Swift Project Documentation

This repository hosts multiple DocC catalogs that provide the source location for documentation content for the Swift project, hosted at www.swift.org.
The repository provides a location to collect and collaborate on Documentation for the Swift open source project.
For more information on the intent and inception, read the Swift Docs Proposal.

Contributions to the Swift Documentation are welcomed and encouraged!

To be a truly great community, Swift Documentation welcomes developers from all walks of life, with different backgrounds, and with a wide range of experience.
A diverse and friendly community has more great ideas, more unique perspectives, and produces more great code.
We work diligently to make the Swift Documentation community welcoming to everyone.

To give clarity of what is expected of our members, Swift has adopted the code of conduct defined by the Contributor Covenant.
This document is used across many open source communities, and we think it articulates our values well.
For more, see the Code of Conduct.

What's in this repository Copy Chapter

The top levels of this repository generally host a very light Swift package that wraps a documentation catalog.
This repository isn't meant for consumable libraries, any documentation for a Swift library should be maintained with that library.
This library hosts general content related to the Swift language, guides, and cross-cutting details that support the Swift ecosystem more broadly.
Each of the catalogs is matched with an entry in the CODEOWNERS file, which provides the technical reviewers for that catalog.

Each directory has it's own Swift package in order to support a full breadth of tooling for documentation and examples, including snippets.
The packages in this repository aren't meant to be depended upon or provide library.

How you can help Copy Chapter

• Report issues with existing content
• Report issues with missing content or request content
• Fix typos
• Propose new content

See contributing for more information on proposing new content, style and content guidelines, and the details of how contributors add content to the Swift Documentation.

File: scripts/README.md Copy Chapter

Local validation Copy Chapter

To build the combined documentation and view the result locally:

• from the docs repository root:

set -e
./scripts/build_docs.py
python3 -m http.server 8123 --directory .build-output

Then in another terminal:

open http://localhost:8123/latest/documentation/

Serve from .build-output (the parent), not .build-output/latest: the build
bakes a /latest/ hosting base path into every asset URL, so the /latest/
prefix must map to the latest/ directory. This example avoids port 8000,
which can be commonly used by other apps or examples.

Note: Ensure that you have a version of Swift available that will build the
content that you point at in sources.json. For latest development tree builds,
that typically requires either the latest Xcode beta or a Swift nightly development
build to support Swift, SwiftPM, swift-testing, and other core projects.

Navigation manifest (combined sidebar curation) Copy Chapter

navigation.json controls the left-hand navigator of the combined archive
(docc merge output): it groups modules under labelled sections, hides
internal modules, and orders them. Hidden modules are also pruned from the
synthesized landing page body (data/documentation.json), so they disappear
from the main page's module list as well as the sidebar. Each entry names a
source (a sources.json id) and the module path it applies to. Every module
in the merged index must be either placed in a group or listed under hidden —
build_docs.py validates and applies this automatically (the
navigator-curation build step), and fails the build on any mismatch or
uncovered module. See hacking-index-json.md for the underlying mechanics.

A group's title is optional — omit it (or set it to null) for a headerless
group whose modules render with no section label in either the sidebar or the
landing page.

A group's modules list may also contain external-link entries — plain
links to content outside the archive, with no backing sources.json id. Give
these a title and an https:// url instead of source/path:

{ "title": "Swift and C++", "url": "https://www.swift.org/documentation/cxx-interop/" }

External entries render in the sidebar only — they get no card on the
synthesized landing page — and aren't valid under hidden (there's no module
to hide). An optional type overrides the sidebar icon; it defaults to
"resources".

Checking the manifest while editing Copy Section

Run the standalone checker — it does not modify any build output:

# From the repo root. Validates navigation.json against sources.json
# (no unknown sources, every source represented) and, if a combined archive
# exists at .build-output/<version>, dry-runs curation and previews the sidebar.
python3 scripts/validate_navigation.py

It exits non-zero when the manifest is invalid or a built archive contains a
module the manifest neither groups nor hides — so it doubles as a coverage
check. Point it at a specific archive (e.g. one you just built elsewhere) with:

python3 scripts/validate_navigation.py --archive path/to/combined.doccarchive

--navigation and --sources can override the input files for experimentation.