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:`.Module` for everything and :py:class:`.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:`.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) 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:`.SettingsBase` for a detailed description of the settings system
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:
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.
i3pystatus uses continuous integration (CI) techniques, which means in our case that every patch and every pull request is tested automatically. While Travis is used for automatic building of GitHub pull requests it is not the authorative CI system (which is Der Golem) for the main repository.
The ci-build.sh
script needs to run successfully for a patch to be
accepted. It can be run on your machine, too, so you don't need to
wait for the often slow Travis build to complete. It does not require
any special privileges, except write access to the ci-build
directory (a different build directory can be specified as the first
parameter to ci-build.sh
).
The script tests the following things:
- PEP8 compliance of the entire codebase, excluding errors of too long lines (error code E501). Line lengths of about 120 characters are acceptable.
- That
setup.py
installs i3pystatus and related binaries (into a location below the build directory) - Unit tests pass, they are tested against the installed version from
2.). A unit test log in JUnit format is generated in the build
directory (
testlog.xml
). - Sphinx docs build without errors or warnings. The HTML docs are
generated in the
docs
directory in the build directory.