Wire documentation is hosted on https://docs.wire.com. This project uses MkDocs as its documentation generator.
Contains the source files and directories for the documentation. The src directory has been migrated from the wire-server docs. The previous version used Sphinx, so we converted it to Markdown and adapted it for MkDocs. See build/old-docs.md for the migration process.
We import documentation pages from the backend repository wire-server. Many files currently reference wire-server, which you can identify using:
find . -type l -printf '%p -> %l\n' | grep './src'Fetch latest updates from wire-server:
git submodule update --remote --checkout --depth 1 -- wire-serverNote: Only run this command when the remote repository has new changes.
Checkout a specific commit:
cd wire-server && git fetch --depth=1 origin <commit-id> && git checkout <commit-id>Verify submodule status:
git submodule statusUpdate changelog (optional): To optionally update the src/changelog/README.md based on the new changelog.md, run the following command:
rm src/changelog/README.md && \
grep '^# ' src/changelog/changelog.md | \
sed 's/^# //' | while IFS= read -r heading; \
do anchor=$(echo "$heading" | sed -E 's/^\[?([0-9-]+)\]? *(\(([^)]+)\)|# *([0-9]+))$/\1-\3\4/' | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g;s/\.//g'); echo "* [$heading](changelog.md#$anchor)"; done > src/changelog/README.mdContains scripts used by the Makefile to support different build use cases. The system is designed to run one build process at a time. All local targets use a temporary directory (stored in .tmpdir file) for building and serving changes due to git operations required by tools like mike for MkDocs.
- make
- nix-shell
- git
- rsync
- Docker (optional) - for building Docker images when testing without nix-shell
Runs the documentation site locally using Mike (MkDocs plugin) for the current branch only. Current changes appear under the latest as the version name. Hosted at 0.0.0.0:8000.
Serves the documentation site locally by building the current branch as static web pages, then hosts a web server using Python's HTTP module. This allows you to preview how the documentation will appear when hosted for the current branch under latest version. Hosted at 0.0.0.0:8000.
Archives the processed web pages for the current branch from the GitHub gh-pages branch (created by make build). Output is generated in the main directory as wire-docs.tar.gz.
Used by run and archive targets to build the current branch. Attempts to identify the version name for the environment. In GitHub environments, it identifies a suitable name for the version being built, based on the type of trigger event, such as a Pull Request, a Push, or the creation of a Tag.
Builds a Docker image for the documentation using the repository's Dockerfile. Uses Python's mike module to host documents (experimental - not the standard Python HTTP module). For testing current changes, use make run or make current instead.
To test the Docker image locally:
docker run -d -p 8000:8000 --restart=always --health-cmd="curl --fail http://localhost:8000 || exit 1" --health-interval=30s --health-retries=3 --health-timeout=5s wire-docsCleans up generated tar files and temporary directories from the build process.
For increased verbosity in make commands:
make SHELL="/bin/bash -x" target graph TD
%% Triggers
PR[Pull Request to main] --> |triggers| BuildWorkflow
PushMain[Push to main Branch] --> |triggers| DeployWorkflow
CreateRelease[Create Release] --> |triggers| ReleaseWorkflow
TestEnvironment[Push to test-dev Branch] --> |triggers| TestWorkflow
%% Styling
classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef action fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
class BuildWorkflow,DeployWorkflow,ReleaseWorkflow,TestWorkflow workflow
class PR,PushMain,CreateRelease,TestEnvironment action
The repository includes four automated builds:
1. Build Test
Runs make build to verify MkDocs build structure for each pull request.
graph TD
%% Build Workflow (PR)
BuildWorkflow[Build Workflow<br/>build.yaml] --> |runs| BuildMake[make build]
BuildMake --> |verifies| DocStructure[Documentation Structure]
DocStructure --> |identifies| NavIssues[Navigation/Markdown Issues]
%% Styling
classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
class BuildWorkflow workflow
class DocStructure,NavIssues output
Runs make archive on every push to the main branch as the latest version. Cleans old latest documents before uploading to ensure the S3 bucket matches the main branch state. Maintains versions.json (tracking all document versions) without overwriting, keeping it synchronized with the latest version with commit as an alias.
graph TD
%% Deploy Workflow (Push to Main)
DeployWorkflow[Deploy Workflow<br/>deploy.yaml] --> |runs| ArchiveMake[make archive]
ArchiveMake --> |creates| LatestVersion[latest Version]
LatestVersion --> |cleans old| OldDocs[Old latest Documents]
LatestVersion --> |pushes to| S3Latest[S3 Bucket - Latest]
LatestVersion --> |maintains| VersionsJSON[versions.json]
%% Styling
classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
class DeployWorkflow workflow
class LatestVersion,S3Latest,VersionsJSON,OldDocs output
Runs make archive when creating new releases, using the git tag (ref_name) as the version. Follows the same cleaning and S3 management process as the production deployment. Creates a release asset equivalent to the make archive output for that git tag.
graph TD
%% Release Workflow (Create Release)
ReleaseWorkflow[Release Workflow<br/>release.yaml] --> |runs| ArchiveMakeRelease[make archive]
ArchiveMakeRelease --> |creates| TaggedVersion[Tagged Version]
TaggedVersion --> |pushes to| S3Tag[S3 Bucket - ref_name]
TaggedVersion --> |maintains| VersionsJSON[versions.json]
TaggedVersion --> |cleans old| OldDocs[Old ref_name Documents]
TaggedVersion --> |creates| ReleaseAsset[Release Asset <br/> wire-docs-ref_name.tar.gz]
%% Styling
classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
class ReleaseWorkflow workflow
class TaggedVersion,ReleaseAsset,S3Tag,VersionsJSON,OldDocs output
Tests the above operations in a staging bucket environment.
graph TD
%% Test Workflow
TestWorkflow[Test Workflow<br/>test.yaml]
TestWorkflow --> |runs| TestArchive[make archive]
TestArchive --> |creates| LatestVersion[latest Version]
LatestVersion --> |cleans old| OldDocs[Old latest Documents Staging]
LatestVersion --> |pushes to| S3Staging[S3 Staging Bucket - Latest]
LatestVersion --> |maintains| VersionsJSON[Staging versions.json]
%% Styling
classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
class TestWorkflow workflow
class LatestVersion,S3Staging,VersionsJSON,OldDocs output
Version numbers follow a three-part format: A.B.C
-
A (Major Version): Indicates the minimum API contract version supported by this release. When this increases, it signals deprecation of older API contract versions. For example, V5.0.0 supports API V5 and newer. Major versions may include breaking changes such as database migrations or backend service structure changes.
-
B (Feature Iteration): Reflects feature updates that don't affect API contract compatibility or introduce breaking changes. For example, V5.1.0 supports API V5 and newer while adding new features or improvements without altering compatibility.
-
C (Fix Iteration): Incremented for bug fixes or security updates that don’t introduce new features or modify compatibility. Fix iterations contain no breaking changes.
Note: The first release, v0.0.0, indicates that the documentation supports all API versions.
-
We provide multiple documentation versions, with each version corresponding to a specific release in the wire-docs repository.
-
Releases are based on Git tags, which mark a specific point in your repository's history.
-
Once a version or tag is released, it becomes immutable. Future updates require creating new versions—no further edits are permitted on existing tags.
-The latest version is regularly updated based on commits to the main branch.