search

NCAS-CMS / cfunits

A Python interface to UNIDATA’s UDUNITS-2 library with CF extensions:
http://ncas-cms.github.io/cfunits
MIT License
11 stars 8 forks source link

Setup doctest and fix broken code examples raised #20

Closed sadielbartholomew closed 3 years ago

sadielbartholomew commented 3 years ago

Quick PR to setup doctest for cfunits and make appropriate amendments to any code examples as raised by corresponding test failures.

With much thanks to @kinow who provided demonstrated how to do this with cf-python (see NCAS-CMS/cf-python#57) and whose code was largely lifted and shifted here. I thought I'd start with cfunits as a much smaller library to set this up as a POC so that we know how doctest works and any quirks it has, so that can gradually chip away at the docstrings in cfdm and then cf-python to make sure they each set themselves up appropriately (as in NCAS-CMS/cf-python#61) and can therefore be doctested too.

Raising as a draft initially since there are still two doctest failure cases, both relating to AttributeErrors when trying to set units on a Units object. I imagine that is deprecated functionality but I just want to check before amending those docstrings.

sadielbartholomew commented 3 years ago

(Comments above were discussed offline. We decided the examples should be removed.)

sadielbartholomew commented 3 years ago

(Force pushed to sort out the merge conflicts locally where they are much easier to manage in emacs. Tests pass locally, now re-triggering the CI via open-close.)

sadielbartholomew commented 3 years ago

Thanks @kinow: doctest is great! :tada: Here it has picked up on a number of deprecated examples and some missing quote marks and the like! cfunits is a small library so it wasn't time consuming to get all examples passing with doctest, but I'll do another of our libraries, cfdm, next by incremental process since there are many, many more docstrings, a lot of which need some logic to set up objects they refer to.

sadielbartholomew commented 3 years ago

(Merging as checks have all passed locally and on the CI.)

kinow commented 3 years ago

It is really great! I have an old Java project with javadocs that contain examples too. Recently found several were broken/outdated, and wished there was something as good as doctest for Java. Thanks Sadie!!!