Skip to content

Contributing

Jump to bottom
Ashley Smith edited this page Oct 16, 2018 · 12 revisions

Read this if you want to contribute. Some ideas for what needs doing, and guidelines on how to do it. The first port of call should be the issue tracker, where more pressing specific issues are listed, and where you can make your own bug reports and feature requests.

Notebooks

Submit to https://github.com/smithara/viresclient_examples or to your own repository. Keep dependencies simple so that anyone can reproduce them easily. Likewise, avoid using any locally stored data in the notebook, so that the notebook is reproducible by itself.

  • Update the notebooks already there with some plots, meaningful descriptive text
  • Define and write some standard notebooks, e.g. :
    • Download dataset ABC, show some quicklooks
    • Reproduce plots made in Swarm product validation reports
    • Download and check large dataset XYZ, save locally. Load again later.
      • Load local file XYZ with dask and show some heavy (but few lines of code) analysis
    • Loading and merging dataframes produced from viresclient, pysat, magpysv, etc.
    • Making animated figures
Related links

It might be possible to link the notebook repo directly into the viresclient docs: http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

Documentation

  • docs are generated by sphinx on readthedocs from .rst files
  • API documentation is automatically built from the docstrings
  • Use Google-style docstrings: http://www.sphinx-doc.org/en/stable/ext/example_google.html
    • (these are processed by the sphinx ext module napoleon)
  • Check docs locally with cd docs; make clean; make html; firefox _build/html/index.html &

Testing

  • Use pytest for testing
  • There are some unit tests but not many, so this should be extended
  • We need some automatic integration testing
    • Write tests that fetch all the data for a day and check that they can be converted to pandas/xarray and have some sensible output (maybe one test for each collection, with separate tests to check behaviour when fetching models)
    • To do this on Travis, then either need to whitelist the Travis IP addresses, or do the authentication somehow (which would be better as it would allow testing that authentication is working)

Overview of viresclient structure

  • [missing]
  • Would be useful to make a class dependency diagram

Packaging & distribution

Currently on PyPI. I would also like to distribute on conda (this will require putting cdflib on conda too).

Instructions for pushing a new release (only I can do this currently):

  1. Make commits and git push
    • Check tests with pytest
    • Check docs with cd docs; make clean; make html; firefox _build/html/index.html &
    • Check installation and tests on Travis-CI
  2. Mark the last commit with git tag v0.2.0
  3. Push to the remote with git push origin --tags
  4. Build package with python setup.py sdist bdist_wheel
  5. Upload to pypi with twine upload dist/*
  6. Log in to readthedocs, check the new version is enabled and set as default
  7. Increment version number in __init__.py so that new commits go on the next version number
Clone this wiki locally