On Wednesday, January 18, 2017 at 9:12:58 PM UTC-5, vk3...@gmail.com wrote:
>
> I have attached the tar.gz file that I *think* will work as an extension
> but I've only managed to test it on my iMac with Weewx installed via the
> 'setup.py' method.
> Can some mind soul(s) please try this out (in a test environment in case
> it generates black holes etc.) before I put it into the repository?
> Also any feedback on the usefulnes (or otherwise) of the 'readme.txt' or
> mistakes in the 'install.py' are welcomed.
>
susan,
in addition to gary's suggestions, i would add the following:
- gary's outline for the readme contents is excellent. please browse the
other drivers from the weewx wiki for examples.
- do not bother with 'manual' instructions in the readme. you should put
detailed instructions about configuration options in the driver itself,
typically in a big block of comments at the beginning of the file and
docstrings for each class/method as appropriate. then possibly use a
subset of that in the readme to explain the options that absolutely must be
set.
- use one of the following: readme, readme.txt, or readme.md. readme.md is
nice if you distribute from github, because it will be automatically
formatted, yet it is still quite readable as plain text. if you're doing
any complicated formatting in the readme, you are probably doing it wrong.
- whichever readme you decide to use, keep each line less than 80 columns
of characters. this may sound like an arcane or anachronistic suggestion,
but there are still many cases where someone must view the readme in a
window/screen that is limited width. random wrapping makes that cumbersome.
- you might want to use 'HP1000Driver' instead of 'xc0422' as the driver
class name.
- set default values for all of the options that are optional. for
example, instead of this:
self.retryCount = float(stn_dict['retry_count'])
do this:
self.retry_count = int(stn_dict.get('retry_count', 3)
- use snake_case for variables instead of camelCase
- run your python code through pylink or pyflakes. or just open it in
pycharm and address all of the warnings.
- for required parameters that have no sane default, instead of this:
self.ipAddressMask = stn_dict['ip_address_mask']
do this:
try:
self.ip_address_mask = stn_dict['ip_address_mask']
except KeyError, e:
raise Exception("required parameter %s has not been specified")
- in the default stanza, include only the parameters that most people will
have to set. in this case you can leave out retry_count and socket_timeout
(assuming that you set defaults in the __init__ method). document what
they do in the docstring for __init__, but no need to put every parameter
in the conf.
m
