doc(tray): Initial experiments

This commit is contained in:
patrick96 2023-04-01 22:51:17 +02:00 committed by Patrick Ziegler
parent df32703a22
commit c6eb3f88ea
6 changed files with 186 additions and 0 deletions

View File

@ -13,6 +13,7 @@
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
# #
import os import os
import sys
from pathlib import Path from pathlib import Path
import datetime import datetime
import sphinx import sphinx
@ -110,6 +111,8 @@ highlight_language = 'none'
smartquotes = False smartquotes = False
primary_domain = 'polybar'
# -- Options for HTML output ------------------------------------------------- # -- 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('deprecated', VersionDirective)
app.add_directive('versionadded', VersionDirective) app.add_directive('versionadded', VersionDirective)
app.add_directive('versionchanged', 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): class VersionDirective(VersionChange):
""" """

48
doc/configdomain.py Normal file
View File

@ -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,
),
]
),
))

View File

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

1
doc/requirements.txt Normal file
View File

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

13
doc/user/modules/defs.rst Normal file
View File

@ -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

112
doc/user/modules/tray.rst Normal file
View File

@ -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