docs: add wpctl man page and Tools documentation section

Add comprehensive wpctl documentation that generates both HTML docs and an installable man page from a single RST source.

Closes: #825

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/conf.py.in

@@ -6,6 +6,10 @@ author = 'Collabora'
 release = '@VERSION@'
 version = '@VERSION@'
 
+# -- General configuration ---------------------------------------------------
+
+smartquotes = False
+
 # -- Breathe configuration ---------------------------------------------------
 
 extensions = [
@@ -43,3 +47,9 @@ html_css_files = ['custom.css']
 graphviz_output_format = "svg"
 
 pygments_style = "friendly"
+
+# -- Options for manual page output -----------------------------------------
+
+man_pages = [
+    ('tools/wpctl', 'wpctl', 'WirePlumber Control CLI', ['The WirePlumber Developers'], 1)
+]

docs/meson.build

@@ -102,6 +102,26 @@ if build_doc
     install_dir: wireplumber_doc_dir,
     build_by_default: true,
   )
+
+  # Generate man pages directory with sphinx
+  custom_target('manpages',
+    command: [sphinx_p,
+      '-q',                       # quiet
+      '-E',                       # rebuild from scratch
+      '-b', 'man',                # man page builder
+      '-d', '@PRIVATE_DIR@',      # doctrees dir
+      '-c', '@OUTDIR@',           # conf.py dir
+      '@CURRENT_SOURCE_DIR@/rst', # source dir
+      '@OUTDIR@',                 # output directory
+    ],
+    depend_files: [
+      sphinx_conf, sphinx_files,
+    ],
+    output: ['wpctl.1'],
+    install: true,
+    install_dir: get_option('mandir') / 'man1',
+    build_by_default: true,
+  )
 endif
 
 # Build GObject introspection

docs/rst/index.rst

@@ -44,6 +44,12 @@ Table of Contents
    scripting/existing_scripts.rst
    scripting/custom_scripts.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Tools
+
+   tools/wpctl.rst
+
 .. toctree::
    :maxdepth: 2
    :caption: Resources

docs/rst/meson.build

@@ -8,4 +8,5 @@ subdir('design')
 subdir('policies')
 subdir('library')
 subdir('scripting')
+subdir('tools')
 subdir('resources')

docs/rst/tools/meson.build

@@ -0,0 +1,3 @@
+sphinx_files += files(
+  'wpctl.rst',
+)

docs/rst/tools/wpctl.rst

@@ -0,0 +1,309 @@
+wpctl(1)
+========
+
+SYNOPSIS
+--------
+
+**wpctl** [*COMMAND*] [*COMMAND_OPTIONS*]
+
+DESCRIPTION
+-----------
+
+**wpctl** is a command-line control tool for WirePlumber, the PipeWire session
+manager. It provides an interface to inspect, control, and configure audio and
+video devices, nodes, and their properties within a PipeWire media server.
+
+WirePlumber manages audio and video routing, device configuration, and session
+policies. **wpctl** allows users to interact with these components, change
+volume levels, set default devices, inspect object properties, and modify
+settings.
+
+COMMANDS
+--------
+
+status
+^^^^^^
+
+**wpctl status** [**-k**\|\ **--nick**] [**-n**\|\ **--name**]
+
+Displays the current state of objects in PipeWire, including devices, sinks,
+sources, filters, and streams. Shows a hierarchical view of the audio/video
+system.
+
+Options:
+  **-k**, **--nick**
+    Display device and node nicknames instead of descriptions
+  **-n**, **--name**
+    Display device and node names instead of descriptions
+
+get-volume
+^^^^^^^^^^
+
+**wpctl get-volume** *ID*
+
+Displays volume information about the specified node, including current volume
+level and mute state.
+
+Arguments:
+  *ID*
+    Node ID or special identifier (see `SPECIAL IDENTIFIERS`_)
+
+inspect
+^^^^^^^
+
+**wpctl inspect** *ID* [**-r**\|\ **--referenced**] [**-a**\|\ **--associated**]
+
+Displays detailed information about the specified object, including all
+properties and metadata.
+
+Arguments:
+  *ID*
+    Object ID or special identifier
+
+Options:
+  **-r**, **--referenced**
+    Show objects that are referenced in properties
+  **-a**, **--associated**
+    Show associated objects
+
+set-default
+^^^^^^^^^^^
+
+**wpctl set-default** *ID*
+
+Sets the specified device node to be the default target of its kind (capture or
+playback) for new streams that require auto-connection.
+
+Arguments:
+  *ID*
+    Sink or source node ID
+
+set-volume
+^^^^^^^^^^
+
+**wpctl set-volume** *ID* *VOL*\ [**%**]\ [**-**\|\ **+**] [**-p**\|\ **--pid**] [**-l** *LIMIT*\|\ **--limit** *LIMIT*]
+
+Sets the volume of the specified node.
+
+Arguments:
+  *ID*
+    Node ID, special identifier, or PID (with --pid)
+  *VOL*\ [**%**]\ [**-**\|\ **+**]
+    Volume specification:
+
+    - *VOL* - Set volume to specific value (1.0 = 100%)
+    - *VOL*\ **%** - Set volume to percentage (50% = 0.5)
+    - *VOL*\ **+** - Increase volume by value
+    - *VOL*\ **-** - Decrease volume by value
+    - *VOL*\ **%+** - Increase volume by percentage
+    - *VOL*\ **%-** - Decrease volume by percentage
+
+Options:
+  **-p**, **--pid**
+    Treat ID as a process ID and affect all nodes associated with it
+  **-l** *LIMIT*, **--limit** *LIMIT*
+    Limit final volume to below this value (floating point, 1.0 = 100%)
+
+Examples:
+  Set volume to 50%: ``wpctl set-volume @DEFAULT_SINK@ 0.5``
+
+  Increase volume by 10%: ``wpctl set-volume 42 10%+``
+
+  Set volume for all nodes of PID 1234: ``wpctl set-volume --pid 1234 0.8``
+
+set-mute
+^^^^^^^^
+
+**wpctl set-mute** *ID* **1**\|\ **0**\|\ **toggle** [**-p**\|\ **--pid**]
+
+Changes the mute state of the specified node.
+
+Arguments:
+  *ID*
+    Node ID, special identifier, or PID (with --pid)
+  **1**\|\ **0**\|\ **toggle**
+    Mute state: 1 (mute), 0 (unmute), or toggle current state
+
+Options:
+  **-p**, **--pid**
+    Treat ID as a process ID and affect all nodes associated with it
+
+set-profile
+^^^^^^^^^^^
+
+**wpctl set-profile** *ID* *INDEX*
+
+Sets the profile of the specified device to the given index.
+
+Arguments:
+  *ID*
+    Device ID or special identifier
+  *INDEX*
+    Profile index (integer, 0 typically means 'off')
+
+set-route
+^^^^^^^^^
+
+**wpctl set-route** *ID* *INDEX*
+
+Sets the route of the specified device to the given index.
+
+Arguments:
+  *ID*
+    Device node ID or special identifier
+  *INDEX*
+    Route index (integer, 0 typically means 'off')
+
+clear-default
+^^^^^^^^^^^^^
+
+**wpctl clear-default** [*ID*]
+
+Clears the default configured node. If no ID is specified, clears all default
+nodes.
+
+Arguments:
+  *ID* (optional)
+    Settings ID to clear (0-2 for Audio/Sink, Audio/Source, Video/Source).
+    If omitted, clears all defaults.
+
+settings
+^^^^^^^^
+
+**wpctl settings** [*KEY*] [*VAL*] [**-d**\|\ **--delete**] [**-s**\|\ **--save**] [**-r**\|\ **--reset**]
+
+Shows, changes, or removes WirePlumber settings.
+
+Arguments:
+  *KEY* (optional)
+    Setting key name
+  *VAL* (optional)
+    Setting value (JSON format)
+
+Options:
+  **-d**, **--delete**
+    Delete the saved setting value (no KEY means delete all)
+  **-s**, **--save**
+    Save the setting value (no KEY means save all, no VAL means current value)
+  **-r**, **--reset**
+    Reset the setting to its default value
+
+Behavior:
+  - No arguments: Show all settings
+  - KEY only: Show specific setting value
+  - KEY and VAL: Set specific setting value
+
+set-log-level
+^^^^^^^^^^^^^
+
+**wpctl set-log-level** [*ID*] *LEVEL*
+
+Sets the log level of a client.
+
+Arguments:
+  *ID* (optional)
+    Client ID. If omitted, applies to WirePlumber. Use 0 for PipeWire server.
+  *LEVEL*
+    Log level (e.g., ``0``, ``1``, ``2``, ``3``, ``4``, ``5``, ``E``, ``W``, ``N``, ``I``, ``D``, ``T``).
+    Use ``-`` to unset the log level.
+
+SPECIAL IDENTIFIERS
+-------------------
+
+Instead of numeric IDs, **wpctl** accepts these special identifiers for
+commonly used defaults:
+
+**@DEFAULT_SINK@**, **@DEFAULT_AUDIO_SINK@**
+  The current default audio sink (playback device)
+
+**@DEFAULT_SOURCE@**, **@DEFAULT_AUDIO_SOURCE@**
+  The current default audio source (capture device)
+
+**@DEFAULT_VIDEO_SOURCE@**
+  The current default video source (camera)
+
+These identifiers are resolved at runtime to the appropriate node IDs.
+
+EXIT STATUS
+-----------
+
+**wpctl** returns the following exit codes:
+
+0
+  Success
+1
+  General error (e.g., invalid arguments, connection failure)
+2
+  Could not connect to PipeWire
+3
+  Command-specific error (e.g., object not found)
+
+EXAMPLES
+--------
+
+Display system status::
+
+    wpctl status
+
+Set default audio sink::
+
+    wpctl set-default 42
+
+Set volume to 75% on default sink::
+
+    wpctl set-volume @DEFAULT_SINK@ 75%
+
+Increase volume by 5% on a specific node::
+
+    wpctl set-volume 42 5%+
+
+Mute the default source::
+
+    wpctl set-mute @DEFAULT_SOURCE@ 1
+
+Toggle mute on default sink::
+
+    wpctl set-mute @DEFAULT_SINK@ toggle
+
+Inspect a device with associated objects::
+
+    wpctl inspect --associated 30
+
+Show all WirePlumber settings::
+
+    wpctl settings
+
+Set a specific setting::
+
+    wpctl settings bluetooth.autoswitch true
+
+Save all current settings::
+
+    wpctl settings --save
+
+Set log level for WirePlumber to debug::
+
+    wpctl set-log-level D
+
+Set log level for a specific client::
+
+    wpctl set-log-level 42 W
+
+NOTES
+-----
+
+Object IDs can be found using the **status** command. The hierarchical display
+shows IDs for devices, nodes, and other objects.
+
+Volume values are floating-point numbers where 1.0 represents 100% volume.
+Values can exceed 1.0 to introduce volume amplification.
+
+When using the **--pid** option, **wpctl** will find all audio nodes associated
+with the specified process ID and apply the operation to all of them.
+
+SEE ALSO
+--------
+
+**pipewire**\ (1), **pw-cli**\ (1), **pw-dump**\ (1), **wireplumber**\ (1)
+
+WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/