Skip to content
Open
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
21 changes: 21 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
version: 2

updates:
# Keeps the SHA pins in .github/workflows up to date. Dependabot reads the
# trailing "# vX.Y.Z" comment on each `uses:` line and rewrites both the SHA
# and the comment together.
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
commit-message:
prefix: ci
# minor and patch bumps arrive as one PR; majors get their own so the
# release notes can be read before merging
groups:
actions:
patterns:
- "*"
update-types:
- minor
- patch
4 changes: 2 additions & 2 deletions .github/workflows/arch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ jobs:
image: archlinux
steps:
- name: Checkout repository actions
uses: actions/checkout@v4
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
sparse-checkout: .github/actions

Expand All @@ -36,7 +36,7 @@ jobs:
image: archlinux
steps:
- name: Checkout repository actions
uses: actions/checkout@v4
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
sparse-checkout: .github/actions

Expand Down
73 changes: 73 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
name: Docs

# PRs build only, to catch broken references before they reach main.
# Pushes to main, and manual runs on main, build and deploy.
on:
push:
branches: [main]
paths:
- docs/**
- VERSION
- .github/workflows/docs.yml
pull_request:
paths:
- docs/**
- VERSION
- .github/workflows/docs.yml
workflow_dispatch:

permissions:
contents: read

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
name: "Docs: Build"
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
# this job executes repo-controlled python (conf.py and any sphinx
# extension it loads), so don't leave the token in .git/config
persist-credentials: false

- name: Install uv
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
enable-cache: true
cache-dependency-glob: docs/uv.lock

# --locked fails if docs/uv.lock is out of date with docs/pyproject.toml.
# -W turns Sphinx warnings into errors, so a broken reference fails here.
- name: Build docs
working-directory: docs
run: uv run --locked sphinx-build -W --keep-going -b html . _build/html

# allowlist the trusted triggers
- name: Upload artifact
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
with:
path: docs/_build/html

deploy:
name: "Docs: Deploy"
needs: build
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
4 changes: 2 additions & 2 deletions .github/workflows/vouch-prs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ jobs:

steps:
- name: Check out template
uses: actions/checkout@v6
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
persist-credentials: false

Expand All @@ -27,7 +27,7 @@ jobs:
>/dev/null

- name: Enforce central Vouch list
uses: mitchellh/vouch/action/check-pr@v1
uses: mitchellh/vouch/action/check-pr@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0
with:
pr-number: ${{ github.event.pull_request.number }}
repo: ${{ github.repository }}
Expand Down
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,8 @@ cmake_install.cmake
compile_commands.json
hyprutils.pc
.envrc

# docs
!docs/Makefile
docs/_build/
docs/.venv/
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@

Hyprutils is a small C++ library for utilities used across the Hypr* ecosystem.

## Documentation

API documentation is published at <https://hyprwm.github.io/hyprutils/>, and its
source lives in [docs/](docs/). To build it locally:

```sh
make -C docs html # output in docs/_build/html
make -C docs live # live-reloading server on 127.0.0.1:8000
```

Python dependencies are handled by [uv](https://docs.astral.sh/uv/); no manual
virtualenv setup is needed.

## Stability

Hyprutils depends on the ABI stability of the stdlib implementation of your compiler. Sover bumps will be done only for hyprutils ABI breaks, not stdlib.
Expand Down
23 changes: 23 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Minimal makefile for Sphinx documentation.
# Python dependencies are managed with uv (see pyproject.toml); `uv run`
# discovers this directory's project and creates/syncs the venv on demand.

UV ?= uv
SPHINXOPTS ?= -W --keep-going
SPHINXBUILD ?= $(UV) run sphinx-build
SOURCEDIR = .
BUILDDIR = _build

.PHONY: help live Makefile

help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

# Live-reloading dev server on http://127.0.0.1:8000
live:
@$(UV) run --group dev sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" \
--ignore "$(BUILDDIR)/*" $(SPHINXOPTS) $(O)

# Catch-all: route everything else to sphinx-build ("make html", "make clean", ...)
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
48 changes: 48 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Configuration file for the Sphinx documentation builder.
# https://www.sphinx-doc.org/en/master/usage/configuration.html

from pathlib import Path

# -- Project information -----------------------------------------------------

project = "hyprutils"
author = "hyprwm"
copyright = "hyprwm"

# Keep the docs in sync with the VERSION file at the repository root.
_version_file = Path(__file__).resolve().parent.parent / "VERSION"
release = _version_file.read_text().strip() if _version_file.is_file() else "unknown"
# MAJOR.MINOR convention
version = ".".join(release.split(".")[:2])

# -- General configuration ---------------------------------------------------

extensions = [
"sphinx_copybutton",
"sphinx_design",
]

exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"]

# Everything here is C++, so default to it for `code-block` and inline roles.
primary_domain = "cpp"
highlight_language = "cpp"

cpp_index_common_prefix = ["Hyprutils::Signal::", "Hyprutils::"]

# -- Options for HTML output -------------------------------------------------

html_theme = "furo"
html_title = f"hyprutils {release}"

html_theme_options = {
"source_repository": "https://github.com/hyprwm/hyprutils/",
"source_branch": "main",
"source_directory": "docs/",
}

# -- Options for sphinx-copybutton -------------------------------------------

# Strip shell prompts so copying a `$ cmd` block yields just `cmd`.
copybutton_prompt_text = r"\$ "
copybutton_prompt_is_regexp = True
43 changes: 43 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
=========
hyprutils
=========

Hyprutils is a small C++ library of utilities used across the Hypr\* ecosystem.
Public headers live under ``include/hyprutils/``, and everything is installed
as a single shared library, ``libhyprutils``.

This documentation is a work in progress. The signal system is documented
first; the remaining modules (``animation``, ``cli``, ``i18n``, ``math``,
``memory``, ``os``, ``path``, ``string``, ``utils``) will follow.

.. toctree::
:maxdepth: 2
:caption: Modules

signal/index

Conventions
===========

* Every public header lives under ``include/hyprutils/<module>/``, and its
symbols live in the matching ``Hyprutils::<Module>`` namespace.
* Types are prefixed by kind: ``C`` for classes, ``I`` for interfaces,
``S`` for plain structs, ``e`` for enums.
* Examples assume the relevant ``using namespace`` unless the qualification
matters to the point being made.

Building the documentation
==========================

Python dependencies are managed with `uv <https://docs.astral.sh/uv/>`_ and
declared in ``docs/pyproject.toml``. No manual venv setup is needed, as ``uv
run`` creates and syncs one on demand.

.. code-block:: sh

$ make -C docs html # output in docs/_build/html
$ make -C docs live # live-reloading server on 127.0.0.1:8000
$ make -C docs clean

Both targets pass ``-W --keep-going``, so warnings are errors. Keep new pages
warning-free, since CI builds with the same flags.
18 changes: 18 additions & 0 deletions docs/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
[project]
name = "hyprutils-docs"
version = "0"
description = "Sphinx documentation for hyprutils"
requires-python = ">=3.11"
dependencies = [
"sphinx>=8.1",
"furo>=2024.8.6",
"sphinx-copybutton>=0.5.2",
"sphinx-design>=0.6.1",
]

[dependency-groups]
dev = ["sphinx-autobuild>=2024.10.3"]

[tool.uv]
# The docs are not a Python package, just an environment to build them in.
package = false
Loading
Loading