60 lines
2.3 KiB
ReStructuredText
60 lines
2.3 KiB
ReStructuredText
|
|
Creating modules
|
|
================
|
|
|
|
Creating new modules ("things that display something") to contribute
|
|
to i3pystatus is reasonably easy. If the module you want to write
|
|
updates it's info periodically, like checking for a network link or
|
|
displaying the status of some service, then we have prepared common
|
|
tools for this which make this even easier:
|
|
|
|
- Common base classes: :py:class:`i3pystatus.core.modules.Module` for
|
|
everything and :py:class:`i3pystatus.core.modules.IntervalModule`
|
|
specifically for the aforementioned usecase of updating stuff
|
|
periodically.
|
|
- Settings (already built into above classes) allow you to easily
|
|
specify user-modifiable attributes of your class for configuration.
|
|
|
|
See :py:class:`i3pystatus.core.settings.SettingsBase` for details.
|
|
- For modules that require credentials, it is recommended to add a
|
|
keyring_backend setting to allow users to specify their own backends
|
|
for retrieving sensitive credentials.
|
|
|
|
Required settings and default values are also handled.
|
|
|
|
Check out i3pystatus' source code for plenty of (`simple
|
|
<https://github.com/enkore/i3pystatus/blob/master/i3pystatus/mem.py>`_)
|
|
examples on how to build modules.
|
|
|
|
The settings system is built to ease documentation. If you specify
|
|
two-tuples like ``("setting", "description")`` then Sphinx will
|
|
automatically generate a nice table listing each option, it's default
|
|
value and description.
|
|
|
|
The docstring of your module class is automatically used as the
|
|
reStructuredText description for your module in the README file.
|
|
|
|
.. seealso::
|
|
|
|
:py:class:`i3pystatus.core.settings.SettingsBase` for a detailed description of the settings system
|
|
|
|
Handling Dependencies
|
|
---------------------
|
|
|
|
To make it as easy as possible to use i3pystatus we explicitly
|
|
document all dependencies in the docstring of a module.
|
|
|
|
The wording usually used goes like this:
|
|
|
|
.. code:: rst
|
|
|
|
Requires the PyPI package `colour`
|
|
|
|
To allow automatic generation of the docs without having all
|
|
requirements of every module installed mocks are used. To make this
|
|
work simply add all modules of dependencies (so no standard library modules
|
|
or modules provided by i3pystatus) you import to the ``MOCK_MODULES``
|
|
list in ``docs/conf.py``. This needs to be the actual name of the imported
|
|
module, so for example if you have ``from somepkg.mod import AClass``,
|
|
you need to add ``somepkg.mod`` to the list.
|