Local build of docs differs from web documentation

[mcgibbon]

I'm looking to submit a documentation PR, but am having trouble getting documentation to build locally with the same result as the web docs.

Steps I am following:

1. Clone repository locally
2. python setup.py build
3. python setup.py install
4. cd docs && make html

Result I expect: The docs in _build/html should be the same as on the web.

Result I get: During build, this is the log:

[mcgibbon@stcu docs]$ make html
Running Sphinx v1.5.2
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                               
/home/disk/eos4/mcgibbon/python/netcdftime/docs/index.rst:11: WARNING: missing attribute mentioned in :members: or __all__: module netcdftime, attribute date2num
/home/disk/eos4/mcgibbon/python/netcdftime/docs/index.rst:11: WARNING: missing attribute mentioned in :members: or __all__: module netcdftime, attribute num2date
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 2 warnings.

Build finished. The HTML pages are in _build/html.

In the resulting html docs, date2num and num2date are missing.

Further to all this, if I add netcdftime.datetime to the list of automodule members on netcdftime, I get the docstring "alias of DatetimeProlepticGregorian", rather than the docstring I get in IPython:

In [4]: nt.datetime?
Docstring:
Phony datetime object which mimics the python datetime object,
but allows for dates that don't exist in the proleptic gregorian calendar.

Supports timedelta operations by overloading + and -.

Has strftime, timetuple, replace, __repr__, and __str__ methods. The
format of the string produced by __str__ is controlled by self.format
(default %Y-%m-%d %H:%M:%S). Supports comparisons with other phony
datetime instances using the same calendar; comparison with
datetime.datetime instances is possible for netcdftime.datetime
instances using 'gregorian' and 'proleptic_gregorian' calendars.

Instance variables are year,month,day,hour,minute,second,microsecond,dayofwk,dayofyr,
format, and calendar.
File:      /home/disk/p/mcgibbon/anaconda/lib/python2.7/site-packages/netcdftime/_netcdftime.so
Type:      type

[dopplershift]

So it works for me locally; I notice two differences in our workflow:

1. I'm building using sphinx 1.7.0; you're using 1.5.2--can you update?
2. I've built and installed just using pip install -e ., which as I understand is the more reliable way to go about installing.

If I add datetime to index.rst, here's what I get:

class netcdftime.datetime
The base class implementing most methods of datetime classes that mimic datetime.datetime but support calendars other than the proleptic Gregorial calendar.

replace()
Return datetime with new specified fields.

[mcgibbon]

Updating Sphinx to v1.7.0 made no difference to what occurs on my end. Uninstalling and re-installing netcdftime in develop mode with pip install -e also made no difference.

[dopplershift]

What version of Cython do you have installed?

[mcgibbon]

Cython version is 0.27.3.

[mcgibbon]

Despite Sphinx saying otherwise, date2num and num2date are in fact in the netcdftime namespace.

In [1]: import cython

In [2]: cython.__version__
Out[2]: '0.27.3'

In [3]: import netcdftime
 
In [4]: dir(netcdftime)
Out[4]: 
['DateFromJulianDay',
 'Datetime360Day',
 'DatetimeAllLeap',
 'DatetimeGregorian',
 'DatetimeJulian',
 'DatetimeNoLeap',
 'DatetimeProlepticGregorian',
 'JulianDayFromDate',
 '__builtins__',
 '__doc__',
 '__file__',
 '__name__',
 '__package__',
 '__path__',
 '__version__',
 '_netcdftime',
 '_parse_date',
 'date2index',
 'date2num',
 'datetime',
 'day_units',
 'hr_units',
 'microsec_units',
 'millisec_units',
 'min_units',
 'num2date',
 'sec_units',
 'time2index',
 'utime']

[mcgibbon]

Actually, that was incorrect. They were only in the namespace because I was running ipython in the netcdftime directory. This is what happens in my home directory:

[mcgibbon@stcu netcdftime]$ cd ..
[mcgibbon@stcu python]$ cd ..
[mcgibbon@stcu ~]$ ipython
Python 2.7.13 | packaged by conda-forge | (default, May  2 2017, 12:48:11) 
Type "copyright", "credits" or "license" for more information.

IPython 4.0.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]: import netcdftime as nt

In [2]: dir(nt)
Out[2]: 
['DateFromJulianDay',
 'Datetime360Day',
 'DatetimeAllLeap',
 'DatetimeGregorian',
 'DatetimeJulian',
 'DatetimeNoLeap',
 'DatetimeProlepticGregorian',
 'JulianDayFromDate',
 '__builtins__',
 '__doc__',
 '__file__',
 '__name__',
 '__package__',
 '__path__',
 '__version__',
 '_netcdftime',
 '_parse_date',
 'date2index',
 'datetime',
 'day_units',
 'hr_units',
 'microsec_units',
 'millisec_units',
 'min_units',
 'sec_units',
 'time2index',
 'utime']

[dopplershift]

I tried doing it with Python 2.7 rather than 3.6...but it still works just fine for me:

Python 2.7.14 | packaged by conda-forge | (default, Dec 25 2017, 01:18:54) 
Type "copyright", "credits" or "license" for more information.

IPython 5.5.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]: import netcdftime as nt

In [2]: dir(nt)
Out[2]: 
['DateFromJulianDay',
 'Datetime360Day',
 'DatetimeAllLeap',
 'DatetimeGregorian',
 'DatetimeJulian',
 'DatetimeNoLeap',
 'DatetimeProlepticGregorian',
 'JulianDayFromDate',
 '__builtins__',
 '__doc__',
 '__file__',
 '__name__',
 '__package__',
 '__path__',
 '__version__',
 '_netcdftime',
 '_parse_date',
 'date2index',
 'date2num',
 'datetime',
 'day_units',
 'hr_units',
 'microsec_units',
 'millisec_units',
 'min_units',
 'num2date',
 'sec_units',
 'time2index',
 'utime']

I'm out of ideas as to what the problem is...though the fact that your dir returns fewer entries points not to a problem with docs, but a problem with building the package itself. What platform?

[spencerkclark]

@mcgibbon do you happen to have netCDF4 installed in your active environment? It's possible you're picking up the netcdftime module from there (rather than this one). That would seem to explain the fact that num2date and date2num are not in the netcdftime namespace, as well as the fact that netcdftime.datetime points to DatetimeProlepticGregorian.

If that's the case, for now I recommend creating a separate environment for editing / building the netcdftime docs (that doesn't have netCDF4 installed).

[dopplershift]

Ah, yes, that would do it. Another option for testing is:

conda remove --force netcdf4

[mcgibbon]

That's almost certainly it. However, that raises an important concern - if a user has netCDF4 installed, does that mean they can't use this netcdftime stand-alone package? Does the netCDF4 package have all the functionality of this package?

[dopplershift]

See these:

Unidata/netcdf4-python#756
Unidata/netcdf4-python#765
Unidata/netcdf4-python#764

[mcgibbon]

Great. Closing this issue.

[jswhit]

The next release (1.3.2) of netcdf4-python will have netcdftime removed.