Repository navigation
Add Documentation with Sphinx and push to Github Pages #121
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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@v6 | ||
| 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@v3 | ||
| 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@v4 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -46,3 +46,8 @@ cmake_install.cmake | |
| compile_commands.json | ||
| hyprutils.pc | ||
| .envrc | ||
|
|
||
| # docs | ||
| !docs/Makefile | ||
| docs/_build/ | ||
| docs/.venv/ | ||
| 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) |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # 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 = [ | ||
| "myst_parser", | ||
| "sphinx_copybutton", | ||
| "sphinx_design", | ||
| ] | ||
|
|
||
| exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"] | ||
|
|
||
| # deflist: term/definition lists. colon_fence: ::: directives, which can wrap | ||
| # ``` code fences without counting backticks. | ||
| myst_enable_extensions = ["deflist", "colon_fence"] | ||
|
|
||
| # Everything here is C++, so default to it for code fences 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 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # 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. | ||
|
|
||
| ```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. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| [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", | ||
| "myst-parser>=4.0", | ||
| ] | ||
|
|
||
| [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 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Signal | ||
|
|
||
| ```cpp | ||
| #include <hyprutils/signal/Signal.hpp> | ||
| #include <hyprutils/signal/Listener.hpp> | ||
|
|
||
| using namespace Hyprutils::Signal; | ||
| ``` | ||
|
|
||
| ```{cpp:namespace} Hyprutils::Signal | ||
| ``` | ||
|
|
||
| The signal module implements a synchronous, single-threaded observer pattern. An | ||
| object exposes one {cpp:class}`CSignalT` per event it can produce, and interested | ||
| parties subscribe to it. Emitting calls every registered handler inline, in | ||
| registration order, and returns once they have all run. There is no queue, no | ||
| dispatch thread, and no allocation per emission. | ||
|
Comment on lines
+15
to
+17
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
This guarantee is inaccurate for any signal with live listeners: Useful? React with 👍 / 👎. |
||
|
|
||
| The module has two halves: | ||
|
|
||
| {doc}`signals` | ||
| : {cpp:class}`CSignalT`, the emitter. It is a variadic template over the types | ||
| the event carries, so handler signatures are checked at compile time instead of | ||
| unpacking a `std::any` at runtime. | ||
|
|
||
| {doc}`listeners` | ||
| : {cpp:class}`CSignalListener`, always held through the | ||
| {cpp:type}`CHyprSignalListener` shared pointer. Ownership of that pointer *is* | ||
| the subscription: when the last strong reference goes away, the handler stops | ||
| being called. | ||
|
|
||
| ## A minimal example | ||
|
|
||
| ```cpp | ||
| CSignalT<> ready; | ||
| CSignalT<int> valueChanged; | ||
|
|
||
| // subscribe; keep the returned handle alive for as long as you want events | ||
| CHyprSignalListener onChange = valueChanged.listen([](int value) { | ||
| printf("value is now %d\n", value); | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. cmon printf in 2026?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's fine, who cares. It's a documentation on signals, not on the right way to print in 2026. |
||
| }); | ||
|
|
||
| valueChanged.emit(42); // prints | ||
| onChange.reset(); // unsubscribe | ||
| valueChanged.emit(7); // nothing happens | ||
| ``` | ||
|
|
||
| ## The ownership model | ||
|
|
||
| The signal holds a *weak* reference to each listener; the subscriber holds the | ||
| *strong* one. That inversion is the central design decision of the module, and it | ||
| has two consequences worth internalising up front. | ||
|
|
||
| **Discarding the result of {cpp:func}`CSignalT::listen` unsubscribes | ||
| immediately.** The temporary shared pointer dies at the end of the full | ||
| expression, taking the listener with it, and the handler never runs. `listen()` | ||
| is marked `[[nodiscard]]` for exactly this reason. | ||
|
|
||
| ```cpp | ||
| signal.listen([] { /* never called */ }); // wrong, and warns | ||
| auto listener = signal.listen([] { /* ok */ }); // right | ||
| ``` | ||
|
|
||
| **Subscriptions are torn down by the subscriber's destructor, for free.** Store | ||
| the handle in the object whose lifetime should bound the subscription and there | ||
| is nothing to unregister by hand, no callback that can fire into a destroyed | ||
| object, and no disconnect API to forget. | ||
|
|
||
| ## The idiomatic shape | ||
|
|
||
| Producers group their signals in an anonymous struct member, so the event set | ||
| reads as a unit and callers write `obj.m_events.something`: | ||
|
|
||
| ```cpp | ||
| class CDevice { | ||
| public: | ||
| struct SButtonEvent { | ||
| uint32_t timeMs = 0; | ||
| uint32_t button = 0; | ||
| bool pressed = false; | ||
| }; | ||
|
|
||
| struct { | ||
| CSignalT<SButtonEvent> button; | ||
| CSignalT<> frame; | ||
| CSignalT<> destroy; | ||
| } m_events; | ||
| }; | ||
| ``` | ||
|
|
||
| Note that events carrying data almost always carry a *single payload struct* | ||
| rather than a list of loose parameters. Adding a field to the struct is source | ||
| compatible with every existing handler; adding a template parameter to the signal | ||
| is not. | ||
|
|
||
| Consumers mirror that with a struct of handles, named after the signals they are | ||
| bound to: | ||
|
|
||
| ```cpp | ||
| class CDeviceWatcher { | ||
| public: | ||
| explicit CDeviceWatcher(CDevice& device) { | ||
| m_listeners.button = device.m_events.button.listen([this](const CDevice::SButtonEvent& event) { | ||
| onButton(event); | ||
| }); | ||
| m_listeners.destroy = device.m_events.destroy.listen([this] { onDestroy(); }); | ||
| } | ||
|
|
||
| // no destructor needed: m_listeners dies with *this, so the lambdas | ||
| // capturing `this` can never be invoked afterwards | ||
|
|
||
| private: | ||
| void onButton(const CDevice::SButtonEvent& event); | ||
| void onDestroy(); | ||
|
|
||
| struct { | ||
| CHyprSignalListener button; | ||
| CHyprSignalListener destroy; | ||
| } m_listeners; | ||
| }; | ||
| ``` | ||
|
|
||
| When the set of subscriptions is not known at compile time, a | ||
| `std::vector<CHyprSignalListener>` or a map keyed by name works the same way: | ||
| erasing the element unsubscribes. See {ref}`storing-listeners`. | ||
|
|
||
| The one place the ownership model does not apply is | ||
| {cpp:func}`CSignalT::listenStatic`, which hands the signal ownership of the | ||
| handler. See {ref}`static-listeners` for when that is the right call. | ||
|
|
||
| ## Thread safety | ||
|
|
||
| There is none. Neither {cpp:class}`CSignalT` nor {cpp:class}`CSignalListener` | ||
| synchronises anything: the listener lists are plain vectors and the reference | ||
| counts behind {cpp:type}`CHyprSignalListener` are non-atomic. Register, emit, and | ||
| destroy on one thread. To cross a thread boundary, hand the event to your event | ||
| loop and emit from the loop's thread. | ||
|
|
||
| ```{toctree} | ||
| :maxdepth: 2 | ||
|
|
||
| signals | ||
| listeners | ||
| ``` | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
where is this gonna push? What's the url?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
github pages, duh!
I know how to Google
I can read and understand github workflows
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(hyprwm.github.io btw. Feel free to suggest changes)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that was my question, the domain. Taking up hyprwm.github.io is kinda yikes. Can't we do /hyprutils?