Make documentation available on readthedocs

[mangecoeur]

Readthedocs is the recommended place to host documentation for python libraries, its provides nice formatting among other features. It would be nice to see netcdf documentation synced there. https://readthedocs.org/

[shoyer]

Unfortunately, this is basically impossible for this package, because we can't install netCDF4-python without installing the netCDF-C library, and ReadTheDocs doesn't have support for installing your own system packages (there are some issues about this in the RTD github repo, but not much progress seems to be being made). If we can't automatically extract docstrings, the value of a tool like ReadTheDocs is pretty limited.

[mangecoeur]

The h5py project shows that it is possible, though I am not sure if they extract class/function docstrings from cython files or rather follow the sphinx pattern of putting them in the documentation .rst files (the idea being to distinguish between end-user documentation and developer commentary). According to the RTD docs if you don't use the "Use Virtualenv" option then the sphinx-build command is simply run in the do source folder and no install is performed, so it doesn't matter if build dependencies are missing.

I think moving to RTD remains valuable - you get discoverability, searchability and a nice theme engine for free, and consistency with other projects.

[shoyer]

You're right -- this is possible in principle. It would require refactoring netCDF4.pyx into a pure Python module wrapping a separate Cython core (this is what h5py does) and also porting the docs to sphinx. Both of these are fine ideas.