From c6eb3f88eab29c37cc8c90aba9eb863bddf9e3bb Mon Sep 17 00:00:00 2001 From: patrick96 Date: Sat, 1 Apr 2023 22:51:17 +0200 Subject: [PATCH] doc(tray): Initial experiments --- doc/conf.py | 6 ++ doc/configdomain.py | 48 ++++++++++++++++ doc/index.rst | 6 ++ doc/requirements.txt | 1 + doc/user/modules/defs.rst | 13 +++++ doc/user/modules/tray.rst | 112 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 186 insertions(+) create mode 100644 doc/configdomain.py create mode 100644 doc/requirements.txt create mode 100644 doc/user/modules/defs.rst create mode 100644 doc/user/modules/tray.rst diff --git a/doc/conf.py b/doc/conf.py index 70c2cf2e..c2d15bcb 100644 --- a/doc/conf.py +++ b/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): """ diff --git a/doc/configdomain.py b/doc/configdomain.py new file mode 100644 index 00000000..194209c1 --- /dev/null +++ b/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, + ), + ] + ), + )) diff --git a/doc/index.rst b/doc/index.rst index d6e27cc3..de61131e 100644 --- a/doc/index.rst +++ b/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: diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..186aa267 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1 @@ +sphinxcontrib-domaintools diff --git a/doc/user/modules/defs.rst b/doc/user/modules/defs.rst new file mode 100644 index 00000000..3ec563a1 --- /dev/null +++ b/doc/user/modules/defs.rst @@ -0,0 +1,13 @@ +.. highlight:: ini + +.. + Substitutions for quickly referencing different config value types + +.. |type-format| replace:: `format `_ +.. |type-extent| replace:: `extent `_ +.. |type-pwo| replace:: `percentage with offset `_ +.. |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 diff --git a/doc/user/modules/tray.rst b/doc/user/modules/tray.rst new file mode 100644 index 00000000..c7b3b340 --- /dev/null +++ b/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 `_ 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: ````: Shows tray icons + :default: ```` + +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 `_ 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 `_ +* `XEmbed Protocol Specification `_ + +.. _systray-spec: https://specifications.freedesktop.org/systemtray-spec/systemtray-spec-latest.html +.. _xembed: https://specifications.freedesktop.org/xembed-spec/xembed-spec-latest.html