From 30a330834feeeab69eccb0a5b432a03d051030b6 Mon Sep 17 00:00:00 2001 From: enkore Date: Wed, 17 Jun 2015 16:05:03 +0200 Subject: [PATCH] Merge formatting and configuration chapters --- docs/configuration.rst | 64 ++++++++++++++++++++++++++++++++++++++++++ docs/formatting.rst | 63 ----------------------------------------- docs/index.rst | 1 - 3 files changed, 64 insertions(+), 64 deletions(-) delete mode 100644 docs/formatting.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index 78a81bc..840bcb0 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -154,3 +154,67 @@ loading process. Currently supported credentials are "password", .. note:: Credential handling requires the PyPI package ``keyring``. Many distributions have it pre-packaged available as ``python-keyring``. + +Formatting +---------- + +All modules let you specifiy the exact output formatting using a +`format string `_, which +gives you a great deal of flexibility. + +If a module gives you a float, it probably has a ton of +uninteresting decimal places. Use ``{somefloat:.0f}`` to get the integer +value, ``{somefloat:0.2f}`` gives you two decimal places after the +decimal dot + +.. _formatp: + +formatp +~~~~~~~ + +Some modules use an extended format string syntax (the :py:mod:`.mpd` +module, for example). Given the format string below the output adapts +itself to the available data. + +:: + + [{artist}/{album}/]{title}{status} + +Only if both the artist and album is known they're displayed. If only one or none +of them is known the entire group between the brackets is excluded. + +"is known" is here defined as "value evaluating to True in Python", i.e. an empty +string or 0 (or 0.0) counts as "not known". + +Inside a group always all format specifiers must evaluate to true (logical and). + +You can nest groups. The inner group will only become part of the output if both +the outer group and the inner group are eligible for output. + +.. _TimeWrapper: + +TimeWrapper +~~~~~~~~~~~ + +Some modules that output times use :py:class:`.TimeWrapper` to format +these. TimeWrapper is a mere extension of the standard formatting +method. + +The time format that should be used is specified using the format specifier, i.e. +with some_time being 3951 seconds a format string like ``{some_time:%h:%m:%s}`` +would produce ``1:5:51``. + +* ``%h``, ``%m`` and ``%s`` are the hours, minutes and seconds without + leading zeros (i.e. 0 to 59 for minutes and seconds) +* ``%H``, ``%M`` and ``%S`` are padded with a leading zero to two digits, + i.e. 00 to 59 +* ``%l`` and ``%L`` produce hours non-padded and padded but only if hours + is not zero. If the hours are zero it produces an empty string. +* ``%%`` produces a literal % +* ``%E`` (only valid on beginning of the string) if the time is null, + don't format anything but rather produce an empty string. If the + time is non-null it is removed from the string. +* When the module in question also uses formatp, 0 seconds counts as + "not known". +* The formatted time is stripped, i.e. spaces on both ends of the + result are removed. diff --git a/docs/formatting.rst b/docs/formatting.rst deleted file mode 100644 index 8de1777..0000000 --- a/docs/formatting.rst +++ /dev/null @@ -1,63 +0,0 @@ -Formatting -========== - -All modules let you specifiy the exact output formatting using a -`format string `_, which -gives you a great deal of flexibility. - -If a module gives you a float, it probably has a ton of -uninteresting decimal places. Use ``{somefloat:.0f}`` to get the integer -value, ``{somefloat:0.2f}`` gives you two decimal places after the -decimal dot - -.. _formatp: - -formatp -------- - -Some modules use an extended format string syntax (the :py:mod:`.mpd` -module, for example). Given the format string below the output adapts -itself to the available data. - -:: - - [{artist}/{album}/]{title}{status} - -Only if both the artist and album is known they're displayed. If only one or none -of them is known the entire group between the brackets is excluded. - -"is known" is here defined as "value evaluating to True in Python", i.e. an empty -string or 0 (or 0.0) counts as "not known". - -Inside a group always all format specifiers must evaluate to true (logical and). - -You can nest groups. The inner group will only become part of the output if both -the outer group and the inner group are eligible for output. - -.. _TimeWrapper: - -TimeWrapper ------------ - -Some modules that output times use :py:class:`.TimeWrapper` to format -these. TimeWrapper is a mere extension of the standard formatting -method. - -The time format that should be used is specified using the format specifier, i.e. -with some_time being 3951 seconds a format string like ``{some_time:%h:%m:%s}`` -would produce ``1:5:51``. - -* ``%h``, ``%m`` and ``%s`` are the hours, minutes and seconds without - leading zeros (i.e. 0 to 59 for minutes and seconds) -* ``%H``, ``%M`` and ``%S`` are padded with a leading zero to two digits, - i.e. 00 to 59 -* ``%l`` and ``%L`` produce hours non-padded and padded but only if hours - is not zero. If the hours are zero it produces an empty string. -* ``%%`` produces a literal % -* ``%E`` (only valid on beginning of the string) if the time is null, - don't format anything but rather produce an empty string. If the - time is non-null it is removed from the string. -* When the module in question also uses formatp, 0 seconds counts as - "not known". -* The formatted time is stripped, i.e. spaces on both ends of the - result are removed. diff --git a/docs/index.rst b/docs/index.rst index 42867b4..421b47e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,6 @@ Contents: :maxdepth: 4 configuration - formatting i3pystatus changelog module