package documentation

[jhamman]

How should we host this package's documentation. Do we want it to live with netcdf4-python? Or should we host it elsewhere?

cc @jswhit @dopplershift

[dopplershift]

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.

[mcgibbon]

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.

[jhamman]

@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.

[mcgibbon]

@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.

[spencerkclark]

@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.

[mcgibbon]

Thanks @spencerkclark that sounds great!

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

[jswhit]

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.

[dopplershift]

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).

[jhamman]

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?

[mcgibbon]

I haven't done it myself, but there are online examples like this one: https://github.com/abingham/cython-sphinx-example

…

On Jan 8, 2017 10:58 PM, "Joe Hamman" ***@***.***> wrote: 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 <https://github.com/dopplershift> - are you the one to ask to get the http://unidata.github.io/netcdftime url setup? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ALvMhf8tC0QwwH-_XH9V-vGDaPK0JuWXks5rQdpogaJpZM4KtET3> .

[dopplershift]

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).

[jswhit]

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

[dopplershift]

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

[jswhit]

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

[ocefpaf]

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.

[dopplershift]

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

[jhamman]

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

[ocefpaf]

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

[jhamman]

@ocefpaf - any progress here?

[ocefpaf]

@ocefpaf - any progress here?

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

[mcgibbon]

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

[jhamman]

closed via #27

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