Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,3 @@ updates:
dependencies:
patterns:
- "*"
- package-ecosystem: pip
directory: /docs
schedule:
interval: monthly
groups:
docs:
patterns:
- "*"
64 changes: 64 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Build the documentation the way `pixi run -e docs docbld` does: Org export,
# API pages from the code, Sphinx with warnings and unresolved references as
# errors, the Zig autodoc site, and the internal link check. External links
# are checked in their own step. On main the site is published to
# https://stackhands.github.io/zig-common/.
name: docs

on:
push:
branches: [main]
pull_request:
workflow_dispatch:
schedule:
# Weekly, so a link that went dead elsewhere is noticed.
- cron: "17 5 * * 1"

permissions:
contents: read

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: prefix-dev/setup-pixi@9936258fee697aff89b3fed6ca1f80a382ef694e # v0.11.3
with:
environments: docs
cache: true
locked: true

- name: Build
run: pixi run -e docs docbld
env:
DOCS_SOURCE_REF: ${{ github.sha }}

- name: External links
run: pixi run -e docs linkcheck
env:
GITHUB_TOKEN: ${{ github.token }}

- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: docs/build/html

deploy:
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
43 changes: 0 additions & 43 deletions .github/workflows/pages.yml

This file was deleted.

13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,16 @@
.zig-cache/
zig-out/
*.o

# Documentation build (docs-plan template): generated, never committed.
/docs/build/
/docs/source/**/*.rst
/docs/source/reference/api/
/docs/source/**/*.png
/docs/source/**/*.svg
/docs/source/**/*.jpg
/docs/source/**/*.webp
!/docs/source/_static/**
/docs/**/__pycache__/
/.pixi/
/.lycheecache
1 change: 1 addition & 0 deletions changelog.d/+doc-comments.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Every `pub` declaration has a doc comment, whose first sentence is the summary the API pages list.
1 change: 1 addition & 0 deletions changelog.d/+docs-pages.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The site has how-to guides for replacing a file and keeping its access control lists, keeping private state in `/tmp`, compressing logs that `.licensed-logs` marks, matching a Python tool's output and upgrading zig-common; explanations of process groups and deadlines, system calls without a C library, and Python compatibility; and a reference of the messages, exit statuses and version line that `cli` gives the tools.
1 change: 1 addition & 0 deletions changelog.d/+docs-site.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The documentation site is built from Org pages in `docs/orgmode/` with Sphinx, in four parts: the tutorial "Write a small tool on zig-common", how-to guides, explanation and reference. Each module's API page is generated from its doc comments, and the site publishes an `objects.inv` of every `pub` declaration for the tools' sites to link into. `pixi run -e docs docbld` builds it as CI does and fails on a warning, an unresolved name or a dead internal link; `pixi run -e docs linkcheck` checks the external links. The `docs` workflow publishes the site to GitHub Pages; `docs/requirements.txt` and `pages.yml` are gone.
2 changes: 0 additions & 2 deletions docs/compat.md

This file was deleted.

69 changes: 0 additions & 69 deletions docs/conf.py

This file was deleted.

Loading
Loading