package documentation about cftime HOT 22 CLOSED

@ocefpaf - any progress here?

Sorry, no. Day job is getting in the way.

from cftime.

To me it makes the most sense to have it separate but on the same service as netcdf4-python. Currently, that would be github pages.

from cftime.

Would really like to see documentation! I'm in need of a datetime object with the built-in datetime API that supports custom calendars, would like to see if this fits the bill.

from cftime.

@mcgibbon - take a look at current netcdftime API in netcdf4-python. That is exactly what you'll be able to get out of this version. @spencerkclark is working on an expanded datetime index API that will probably live in xarray.

@jswhit and @dopplershift - if you can give a few pointers as to how we should go about getting the documentation build, I can try to hack that together this week. Presumably, we want it to be found at a URL like http://unidata.github.io/netcdftime.

from cftime.

@jhamman I couldn't find any documentation on netcdftime in the netcdf4-python documentation. help() in python was also unhelpful. All I could find was "Otherwise, they are 'phony' datetime objects which support some but not all the methods of 'real' python datetime objects.". I'm trying to find out whether they support arithmetic operations with timedelta objects, and what calendars are supported.

from cftime.

@mcgibbon I'm not aware of extensive formal documentation of netcdftime datetime objects; however I think I can answer your questions.

The answer is yes, as of Unidata/netcdf4-python#594 netcdftime objects support datetime arithmetic. In addition, a list of supported calendars can be found in the documentation of the num2date function of netcdf4-python.

E.g. one can write:

In [1]: from netCDF4 import num2date
In [2]: example = num2date([0, 28], 'days since 2000-02-01', calendar='noleap')
In [3]: example
Out[3]:
array([netcdftime._netcdftime.DatetimeNoLeap(2000, 2, 1, 0, 0, 0, 0, 3, 32),
       netcdftime._netcdftime.DatetimeNoLeap(2000, 3, 1, 0, 0, 0, 0, 3, 60)], dtype=object)
In [4]: example[1] - example[0]
Out[4]: datetime.timedelta(28)

One can also construct datetime objects for different calendars more directly. So for example if you know you'll want to use a 'noleap' calendar you can write:

In [1]: from netcdftime import DatetimeNoLeap
In [2]: DatetimeNoLeap(2000, 2, 1)
Out[2]: netcdftime._netcdftime.DatetimeNoLeap(2000, 2, 1, 0, 0, 0, 0, -1, 1)
In [3]: DatetimeNoLeap(2000, 3, 1) - DatetimeNoLeap(2000, 2, 1)
Out[3]: datetime.timedelta(28)

The following special calendar datetime objects are available:
DatetimeGregorian, DatetimeProlepticGregorian, Datetime360Day, DatetimeJulian, DatetimeAllLeap, DatetimeNoLeap. For standard calendars netcdftime uses ordinary datetime.datetime objects.

from cftime.

Thanks @spencerkclark that sounds great!

Anyone know the timeline on when this will be available for install via pypi/pip?

from cftime.

The only documentation on the netcdf4-python site is for the num2date and date2num convenience functions, since this is the way most people access the functionality. I think it makes sense to create documentation for the lower level functions of the netcdftime module and host it at http://unidata.github.io/netcdftime. Right now the docstrings use epydoc markup, but epydoc appears to be dead. I converted the docstrings in netCDF4 to use pdoc some time ago, but never got around to fixing the netcdftime docstrings. I used a my own fork of pdoc that is hacked to include the signatures of cython functions (pull request here). Shouldn't be too hard to convert the netcdftime docstrings to use this also, at least as a first cut.

from cftime.

Do you have an argument against sphinx? That's what numpy uses and a lot of effort has been put into tools around that (like sphinx-gallery).

from cftime.

I'd also like to use sphinx if at all possible. Does any have experience putting it to work for a cython project? I gave in 15 minutes this evening but wasn't able to get it to work.

@dopplershift - are you the one to ask to get the http://unidata.github.io/netcdftime url setup?

from cftime.

from cftime.

Getting that URL active is a GitHub thing actually: GitHub Pages; it's as simple as pushing to the gh-pages branch (or a couple other options) and tweaking the repo settings. Now if sphinx is the path forward, you have to set up a Travis job to build the docs and push to the branch, but luckily there's a tool called doctr that should simplify the process.

I'm happy to help with any of that as well--though my ability is limited until after I get through AMS crunch (starts Jan 21st).

from cftime.

I think the problem I had with sphinx is that it won't correctly process docstrings in cython extension modules.

from cftime.

Cython is used in numpy now, so between stealing from them and the link above we should have the resources necessary.

from cftime.

I agree Sphinx is the way to go if you can get it to work with Cython.

from cftime.

What is the current status on this? If no one is working on it I can try to get something into a PR this weekend.

from cftime.

I haven't done anything...if you put stuff on a gh-pages branch, I'll twiddle the repository settings as necessary.

from cftime.

I started on it months ago but don't think I got anywhere. If you can push it forward, that would be awesome!

from cftime.

I'll try to address this over the weekend. (I'd like to get a release on PyPI before SciPy if possible.)

from cftime.

@ocefpaf - any progress here?

from cftime.

Looking forward to updating sympl's documentation to talk about this!

from cftime.

closed via #27

see https://unidata.github.io/netcdftime/

from cftime.