From 3a5365a2c3bde494c79595e19674c1760debaba6 Mon Sep 17 00:00:00 2001 From: tobi-wan-kenobi Date: Sun, 6 Sep 2020 14:09:18 +0200 Subject: [PATCH] [doc] add testing guidelines, general improvements --- docs/development/general.rst | 37 +++++++++--------------------------- docs/development/index.rst | 1 + docs/development/testing.rst | 33 ++++++++++++++++++++++++++++++++ docs/modules.rst | 36 ++++++++++++++++++++++++++++++++--- 4 files changed, 76 insertions(+), 31 deletions(-) create mode 100644 docs/development/testing.rst diff --git a/docs/development/general.rst b/docs/development/general.rst index 824d1a7..0ec89a0 100644 --- a/docs/development/general.rst +++ b/docs/development/general.rst @@ -1,34 +1,15 @@ General guidelines ================== -Writing unit tests ------------------- +Not much, right now. If you have an idea and some code, just +create a PR, I will gladly review and comment (and, likely, merge) -Some general hints: +Just one minor note: ``bumblebee-status`` is mostly a one-person, +spare-time project, so please be patient when answering an issue, +question or PR takes a while. -- Tests should run with just Python Standard Library modules installed - (i.e. if there are additional requirements, the test should be skipped - if those are missing) -- Tests should run even if there is no network connectivity (please mock - urllib calls, for example) -- Tests should be stable and not require modifications every time the - tested code's implementation changes slightly (been there / done that) +Also, the (small) community that has gathered around ``bumblebee-status`` +is extremely friendly and helpful, so don't hesitate to create issues +with questions, somebody will always come up with a useful answer. -Right now, ``bumblebee-status`` is moving away from Python's -built-in ``unittest`` framework (tests located inside ``tests/``) -and towards ``pytest`` (tests located inside ``pytests/``). - -First implication: To run the new tests, you need to have ``pytest`` -installed, it is not part of the Python Standard Library. Most -distributions call the package ``python-pytest`` or ``python3-pytest`` -or something similar (or you just use ``pip install --use pytest``) - -Aside from that, you just write your tests using ``pytest`` as usual, -with one big caveat: - -**If** you create a new directory inside ``pytests/``, you need to -also create a file called ``__init__.py`` inside that, otherwise, -modules won't load correctly. - -For examples, just browse the existing code. A good, minimal sample -for unit testing ``bumblebee-status`` is ``pytests/core/test_event.py``. +:) diff --git a/docs/development/index.rst b/docs/development/index.rst index 179dee0..6881fdb 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -8,4 +8,5 @@ Developer's Guide general module theme + testing diff --git a/docs/development/testing.rst b/docs/development/testing.rst new file mode 100644 index 0000000..c5c9375 --- /dev/null +++ b/docs/development/testing.rst @@ -0,0 +1,33 @@ +Testing guidelines +================== + +Writing unit tests +------------------ + +Some general hints: + +- Tests should run with just Python Standard Library modules installed + (i.e. if there are additional requirements, the test should be skipped + if those are missing) +- Tests should run even if there is no network connectivity (please mock + urllib calls, for example) +- Tests should be stable and not require modifications every time the + tested code's implementation changes slightly (been there / done that) + +Right now, ``bumblebee-status`` uses the ``pytest`` framework, and its +unit tests are located inside the ``tests/`` subdirectory. + +First implication: To run the new tests, you need to have ``pytest`` +installed, it is not part of the Python Standard Library. Most +distributions call the package ``python-pytest`` or ``python3-pytest`` +or something similar (or you just use ``pip install --use pytest``) + +Aside from that, you just write your tests using ``pytest`` as usual, +with one big caveat: + +**If** you create a new directory inside ``tests/``, you need to +also create a file called ``__init__.py`` inside that, otherwise, +modules won't load correctly. + +For examples, just browse the existing code. A good, minimal sample +for unit testing ``bumblebee-status`` is ``tests/core/test_event.py``. diff --git a/docs/modules.rst b/docs/modules.rst index 09879f7..18b3806 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -278,6 +278,7 @@ Parameters: * vault.location: Location of the password store (defaults to ~/.password-store) * vault.offx: x-axis offset of popup menu (defaults to 0) * vault.offy: y-axis offset of popup menu (defaults to 0) + * vault.text: Text to display on the widget (defaults to ) Many thanks to `bbernhard `_ for the idea! @@ -294,6 +295,9 @@ Parameters: and appending a file '~/.config/i3/config.' for every screen. * xrandr.autoupdate: If set to 'false', does *not* invoke xrandr automatically. Instead, the module will only refresh when displays are enabled or disabled (defaults to true) + * xrandr.exclude: Comma-separated list of display name prefixes to exclude + * xrandr.autotoggle: Boolean flag to automatically enable new displays (defaults to false) + * xrandr.autotoggle_side: Which side to put autotoggled displays on ('right' or 'left', defaults to 'right') Requires the following python module: * (optional) i3 - if present, the need for updating the widget list is auto-detected @@ -636,9 +640,6 @@ Displays DNF package update information (///`_ - many thanks! .. image:: ../screenshots/dunst.png +dunstctl +~~~~~~~~ + +Toggle dunst notifications using dunstctl. + +When notifications are paused using this module dunst doesn't get killed and you'll keep getting notifications on the background that will be displayed when unpausing. +This is specially useful if you're using dunst's scripting (https://wiki.archlinux.org/index.php/Dunst#Scripting), which requires dunst to be running. Scripts will be executed when dunst gets unpaused. + +Requires: + * dunst v1.5.0+ + +contributed by `cristianmiranda `_ - many thanks! + getcrypto ~~~~~~~~~ @@ -1303,6 +1317,22 @@ contributed by `chdorb `_ - many thanks! .. image:: ../screenshots/taskwarrior.png +thunderbird +~~~~~~~~~~~ + +Displays the unread emails count for one or more Thunderbird inboxes + +Parameters: + * thunderbird.home: Absolute path of your .thunderbird directory (e.g.: /home/pi/.thunderbird) + * thunderbird.inboxes: Comma separated values for all MSF inboxes and their parent directory (account) (e.g.: imap.gmail.com/INBOX.msf,outlook.office365.com/Work.msf) + +Tips: + * You can run the following command in order to list all your Thunderbird inboxes + + find ~/.thunderbird -name '*.msf' | awk -F '/' '{print $(NF-1)"/"$(NF)}' + +contributed by `cristianmiranda `_ - many thanks! + timetz ~~~~~~