generate a man page

Makefile

@@ -6,13 +6,14 @@ BINDIR ?= $(DESTDIR)$(PREFIX)/bin
 ZSHDIR ?= $(DESTDIR)$(PREFIX)/share/zsh
 BSHDIR ?= $(DESTDIR)$(PREFIX)/share/bash-completions
 
-CC = clang
-CFLAGS ?= -g -ggdb -O2 -fPIE -pie -flto -D_FORTIFY_SOURCE=2 -fstack-protector-strong --param=ssp-buffer-size=1 -Weverything -Werror -std=c11 -fsanitize=undefined -fsanitize-trap=undefined -Wl,-z,relro,-z,now
+include Makerules
 CFLAGS += -Wno-disabled-macro-expansion
 
-.PHONY: all clean clang-analyze cov-build install uninstall
+.PHONY: all bin clean clang-analyze cov-build doc install uninstall
 
-all: dist
+all: dist bin doc
+
+bin: dist
 	@$(CC) $(CFLAGS) src/$(PROGNM).c -o dist/$(PROGNM)
 
 clean:
@@ -21,6 +22,14 @@ clean:
 dist:
 	@mkdir -p ./dist
 
+doc: dist
+	@(cd doc; \
+		sphinx-build -b man -Dversion=$(VER) \
+			-d doctree -E . ../dist $(PROGNM).rst; \
+		rm -r -- doctree; \
+	)
+
+
 cov-build: dist
 	@cov-build --dir cov-int ./make.sh
 	@tar czvf $(PROGNM).tgz cov-int
@@ -30,8 +39,10 @@ clang-analyze:
 
 install:
 	@install -Dm755 dist/$(PROGNM) $(BINDIR)/$(PROGNM)
+	@install -Dm755 dist/$(PROGNM).1 $(DOCDIR)/$(PROGNM).1
 	@install -Dm755 90-backlight.rules $(LIBDIR)/udev/rules.d/90-backlight.rules
 
 uninstall:
 	@rm -f -- $(BINDIR)/$(PROGNM)
+	@rm -f -- $(DOCDIR)/$(PROGNM).1
 	@rm -f -- $(LIBDIR)/udev/rules.d/90-backlight.rules

Makerules

@@ -0,0 +1,3 @@
+CC = clang
+CFLAGS ?= -g -ggdb -O3 -fPIE -pie -flto -D_FORTIFY_SOURCE=2 -fstack-protector-strong --param=ssp-buffer-size=1 -Weverything -Werror -std=c11 -fsanitize=undefined -fsanitize-trap=undefined -Wl,-z,relro,-z,now
+VER = v0-`git rev-list --count HEAD`

PKGBUILD

@@ -9,7 +9,7 @@ url='https://github.com/HalosGhost/enlighten'
 arch=('i686' 'x86_64')
 license=('GPL3')
 
-makedepends=('git' 'clang')
+makedepends=('git' 'clang' 'python-docutils')
 
 source=('git+https://github.com/HalosGhost/enlighten.git')
 sha256sums=('SKIP')

doc/conf.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+project = 'enlighten'
+master_doc = 'enlighten'
+source_suffix = '.rst'
+
+show_authors = False
+today_fmt = '%d %b %Y'
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('enlighten', 'enlighten', 'A simple command-line tool to manage sysfs-exposed backlight devices', [], 1)
+]

doc/enlighten.rst

@@ -0,0 +1,70 @@
+enlighten
+=========
+
+Synopsis
+--------
+
+**enlighten** [ help | list | [+-]<#>[%] ]
+
+Description
+-----------
+
+:program:`enlighten` is a command-line tool to manage sysfs-exposed backlights
+
+Options
+-------
+
+<no argument>
+    Display current brightness information (formatted: ``cur / max (perc)``)
+
+help
+    Print help summary and exit.
+
+list
+    Print a list of known backlight device names.
+
+``[+-]<#>[%]``
+    Adjust the current brightness to ``#``.
+    If a sign (``+`` or ``-``) is specified, adjust relative to the current brightness.
+    If ``%`` is specifiec, treat ``#`` as a percent of the maximum.
+
+Environment Variables
+---------------------
+
+:program:`enlighten` recognizes three environment variables for runtime configuration:
+
+BACKLIGHT_DEVICE
+    Holds the name of the device to query/adjust.
+
+BACKLIGHT_THRESHOLD_MIN
+    Holds a value of the form ``<#>[%]`` that represents a saturating minimum brightness.
+    If the user-specified value would change the backlight's brightness to be less than this minimum, the brightness will be set to this minimum instead.
+    If not specified, defaults to ``0``.
+
+BACKLIGHT_THRESHOLD_MAX
+    Holds a value of the form ``<#>[%]`` that represents a saturating maximum brightness.
+    If the user-specified value would change the backlight's brightness to be greater than this maximum, the brightness will be set to this maximum instead.
+    If not specified, defaults to "100%".
+
+Examples
+--------
+
+enlighten h
+    print the help summary.
+
+enlighten l
+    print a list of known backlight device names.
+
+enlighten
+    print the current brightness information.
+
+enlighten +25%
+    increase the brightness by 25 percent of the maximum.
+
+enlighten 75%
+    set the brightness to 75 percent of the maximum.
+
+Bugs
+----
+
+Report bugs for enlighten to https://github.com/HalosGhost/enlighten/issues