doc(tray): Initial experiments

doc/conf.py

@@ -13,6 +13,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import sys
 from pathlib import Path
 import datetime
 import sphinx
@@ -110,6 +111,8 @@ highlight_language = 'none'
 
 smartquotes = False
 
+primary_domain = 'polybar'
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -240,6 +243,9 @@ if packaging.version.parse(sphinx.__version__) >= packaging.version.parse("1.8.5
     app.add_directive('deprecated', VersionDirective)
     app.add_directive('versionadded', VersionDirective)
     app.add_directive('versionchanged', VersionDirective)
+    sys.path.insert(0, os.path.abspath(doc_path))
+    from configdomain import myDomain
+    app.add_domain(myDomain)
 
   class VersionDirective(VersionChange):
     """

doc/configdomain.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+    configdomain
+    ~~~~~~~~~~~~
+
+    TODO document
+"""
+
+from sphinxcontrib.domaintools import custom_domain
+from sphinx.util.docfields import Field, GroupedField
+
+__version__ = "0.1.0"
+# for this module's sphinx doc
+release = __version__
+version = release.rsplit('.', 1)[0]
+
+
+myDomain = custom_domain('PolybarConfigDomain',
+                         name='polybar',
+                         label="Polybar Configuration",
+
+                         elements=dict(
+                             setting=dict(
+                                 objname="Config Setting",
+                                 fields=[
+                                     Field('type',
+                                           label="Type",
+                                           names=['type'],
+                                           has_arg=False,
+                                           ),
+                                     Field('tags',
+                                           label="Available Tags",
+                                           names=['tags'],
+                                           has_arg=False,
+                                           ),
+                                     Field('tokens',
+                                           label="Supported Tokens",
+                                           names=['tokens'],
+                                           has_arg=False,
+                                           ),
+                                     Field('default',
+                                           label="Default Value",
+                                           names=['default'],
+                                           has_arg=False,
+                                           ),
+                                 ]
+                             ),
+                         ))

doc/index.rst

@@ -15,6 +15,12 @@ Welcome to the official polybar documentation.
    user/actions
    user/ipc
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Modules:
+
+   user/modules/tray
+
 .. toctree::
    :maxdepth: 1
    :caption: Manual Pages:

doc/requirements.txt

@@ -0,0 +1 @@
+sphinxcontrib-domaintools

doc/user/modules/defs.rst

@@ -0,0 +1,13 @@
+.. highlight:: ini
+
+..
+  Substitutions for quickly referencing different config value types
+
+.. |type-format| replace:: `format <type-format_>`_
+.. |type-extent| replace:: `extent <type-extent_>`_
+.. |type-pwo| replace:: `percentage with offset <type-pwo_>`_
+.. |type-color| replace:: color
+
+.. _type-format: https://github.com/polybar/polybar/wiki/Formatting#formats
+.. _type-extent: https://github.com/polybar/polybar/wiki/Formatting#extent
+.. _type-pwo: https://github.com/polybar/polybar/wiki/Formatting#percentage-with-offset

doc/user/modules/tray.rst

@@ -0,0 +1,112 @@
+.. include:: defs.rst
+
+Tray Module
+===========
+
+.. versionadded:: 3.7.0
+
+The tray module displays system tray application icons on the bar.
+
+This module is a bit different from the other modules.
+The tray icons (also called clients) are individual windows managed by their
+respective application (e.g. the Dropbox tray icon is created and managed by
+the Dropbox application).
+Polybar is only responsible for embedding the windows in the bar and
+positioning them correctly.
+
+.. note::
+
+   Only a single instance of this module can be active at the same time (across
+   all polybar instances).
+
+   The way the `system tray protocol <systray-spec_>`_ works, at most one tray
+   can exist at any time.
+   Polybar will produce a warning if additional tray instances are created.
+
+For transparent background colors, the tray will use pseudo-transparency, true
+transparency is not possible for the tray icons.
+
+TODO mention the ``type`` setting somewhere
+
+Formats
+-------
+
+The module only has a single format:
+
+.. setting:: format
+
+  :type: |type-format|
+  :tags: ``<tray>``: Shows tray icons
+  :default: ``<tray>``
+
+Settings
+--------
+
+.. setting:: tray-spacing
+
+  Space added between tray icons
+
+  :type: |type-extent|, non-negative
+  :default: ``0px``
+
+.. setting:: tray-padding
+
+  Space added before and after each tray icon
+
+  :type: |type-extent|, non-negative
+  :default: ``0px``
+
+.. setting:: tray-size
+
+  Size of individual tray icons
+
+  Relative to bar height
+
+  :type: |type-pwo|, non-negative
+  :default: 66%
+
+.. setting:: tray-background
+
+  Background color of tray icons
+
+  .. note::
+    This only affects the color of the individual icons and not the space in
+    between, changing this setting will likely not look good.
+
+  :type: |type-color|
+  :default: ``${root.background}``
+
+.. setting:: tray-foreground
+
+  Tray icon color hint
+
+  This serves as a hint to the tray icon application what color to use for the
+  icon.
+
+  This is not guaranteed to have any effect (likely only in GTK3) because it
+  targets a non-standard part of the `system tray protocol <systray-spec_>`_ by
+  setting the ``_NET_SYSTEM_TRAY_COLORS`` atom on the tray window.
+
+  :type: |type-color|
+  :default: ``${tray-foreground}``
+
+
+Example
+-------
+
+::
+
+  [module/tray]
+  type = internal/tray
+
+  format-margin = 8px
+  tray-spacing = 8px
+
+References
+----------
+
+* `System Tray Protocol Specification <systray-spec_>`_
+* `XEmbed Protocol Specification <xembed_>`_
+
+.. _systray-spec: https://specifications.freedesktop.org/systemtray-spec/systemtray-spec-latest.html
+.. _xembed: https://specifications.freedesktop.org/xembed-spec/xembed-spec-latest.html