Update README

[milancurcic]

This PR makes a few updates to the README:

• Use active voice in the first sentence
• Remove note about system libs and pip
• Add instructions to build locally with pip
• Bring docs and examples links to the top (fixes Update README.m #106)

[philippemiron]

The changes are ok.

I don't want to sound like a pip hater, but in practice, it just doesn't work for complex environment. Our package is not even that complex but still fails, as you can see from the test I just did on a raspberry pi I used as a server. I don't have any Windows machines to test, but I would expect the same results.

So I don't think we should pip instructions to run the tests as it will most likely fail on anyone following those steps. If someone already uses pip to manage their environment, my guess is that they can figure it out from the conda steps.

---

git clone https://github.com/cloud-drift/clouddrift
cd clouddrift/

$ python3 -m venv .venv
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

so I installed this:

sudo apt-get install python3-venv

Now the .venv worked.

$ pip install .
Defaulting to user installation because normal site-packages is not writeable
Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Processing /home/pi/Downloads/clouddrift
  DEPRECATION: A future pip version will change local packages to be built in-place without first copying to a temporary directory. We recommend you use --use-feature=in-tree-build to test your packages with this new behavior before it becomes the default.
   pip 21.3 will remove support for this functionality. You can find discussion regarding this at https://github.com/pypa/pip/issues/7555.
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Collecting fsspec>=2022.3.0
  Downloading https://www.piwheels.org/simple/fsspec/fsspec-2023.1.0-py3-none-any.whl (143 kB)
     |████████████████████████████████| 143 kB 347 kB/s 
Collecting tqdm>=4.64.0
  Downloading https://www.piwheels.org/simple/tqdm/tqdm-4.64.1-py2.py3-none-any.whl (78 kB)
     |████████████████████████████████| 78 kB 254 kB/s 
Collecting awkward>=2.0.0
  Downloading https://www.piwheels.org/simple/awkward/awkward-2.0.8-py3-none-any.whl (583 kB)
     |████████████████████████████████| 583 kB 355 kB/s 
Collecting pyarrow>=8.0.0
  Downloading pyarrow-11.0.0.tar.gz (1.0 MB)
     |████████████████████████████████| 1.0 MB 3.3 MB/s 
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Collecting xarray>=2022.3.0
  Downloading https://www.piwheels.org/simple/xarray/xarray-2023.2.0-py3-none-any.whl (975 kB)
     |████████████████████████████████| 975 kB 1.4 kB/s 
Collecting netcdf4>=1.5.8
  Downloading netCDF4-1.6.2.tar.gz (777 kB)
     |████████████████████████████████| 777 kB 6.8 MB/s 
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  ERROR: Command errored out with exit status 1:
   command: /usr/bin/python3 /home/pi/.local/lib/python3.9/site-packages/pip/_vendor/pep517/in_process/_in_process.py get_requires_for_build_wheel /tmp/tmpshxrjtim
       cwd: /tmp/pip-install-rca3sha8/netcdf4_83a32ed78aae4d31875ede73af939234
  Complete output (37 lines):
  Package hdf5 was not found in the pkg-config search path.
  Perhaps you should add the directory containing `hdf5.pc'
  to the PKG_CONFIG_PATH environment variable
  No package 'hdf5' found
  reading from setup.cfg...
  
      HDF5_DIR environment variable not set, checking some standard locations ..
  checking /home/pi/include ...
  hdf5 headers not found in /home/pi/include
  checking /usr/local/include ...
  hdf5 headers not found in /usr/local/include
  checking /sw/include ...
  hdf5 headers not found in /sw/include
  checking /opt/include ...
  hdf5 headers not found in /opt/include
  checking /opt/local/include ...
  hdf5 headers not found in /opt/local/include
  checking /opt/homebrew/include ...
  hdf5 headers not found in /opt/homebrew/include
  checking /usr/include ...
  hdf5 headers not found in /usr/include
  Traceback (most recent call last):
    File "/home/pi/.local/lib/python3.9/site-packages/pip/_vendor/pep517/in_process/_in_process.py", line 280, in <module>
      main()
    File "/home/pi/.local/lib/python3.9/site-packages/pip/_vendor/pep517/in_process/_in_process.py", line 263, in main
      json_out['return_val'] = hook(**hook_input['kwargs'])
    File "/home/pi/.local/lib/python3.9/site-packages/pip/_vendor/pep517/in_process/_in_process.py", line 114, in get_requires_for_build_wheel
      return hook(config_settings)
    File "/tmp/pip-build-env-a70d5i_e/overlay/lib/python3.9/site-packages/setuptools/build_meta.py", line 338, in get_requires_for_build_wheel
      return self._get_build_requires(config_settings, requirements=['wheel'])
    File "/tmp/pip-build-env-a70d5i_e/overlay/lib/python3.9/site-packages/setuptools/build_meta.py", line 320, in _get_build_requires
      self.run_setup()
    File "/tmp/pip-build-env-a70d5i_e/overlay/lib/python3.9/site-packages/setuptools/build_meta.py", line 335, in run_setup
      exec(code, locals())
    File "<string>", line 449, in <module>
    File "<string>", line 390, in _populate_hdf5_info
  ValueError: did not find HDF5 headers
  ----------------------------------------
WARNING: Discarding https://files.pythonhosted.org/packages/a6/f9/12f43c2e31d1c7aae0827820ae747fa4c7cc382b38dab11e8c11575d3af6/netCDF4-1.6.2.tar.gz#sha256=0382b02ff6a288419f6ffec85dec40f451f41b8755547154c575ddd9f0f4ae53 (from https://pypi.org/simple/netcdf4/) (requires-python:>=3.6). Command errored out with exit status 1: /usr/bin/python3 /home/pi/.local/lib/python3.9/site-packages/pip/_vendor/pep517/in_process/_in_process.py get_requires_for_build_wheel /tmp/tmpshxrjtim Check the logs for full command output.
  Downloading netCDF4-1.6.1.tar.gz (776 kB)
     |████████████████████████████████| 776 kB 7.4 MB/s 
    ERROR: Command errored out with exit status 1:
     command: /usr/bin/python3 -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-rca3sha8/netcdf4_bea74f98f91244bda844919dcb89626a/setup.py'"'"'; __file__='"'"'/tmp/pip-install-rca3sha8/netcdf4_bea74f98f91244bda844919dcb89626a/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-mfsa_0ml
         cwd: /tmp/pip-install-rca3sha8/netcdf4_bea74f98f91244bda844919dcb89626a/
    Complete output (28 lines):
    Package hdf5 was not found in the pkg-config search path.
    Perhaps you should add the directory containing `hdf5.pc'
    to the PKG_CONFIG_PATH environment variable
    No package 'hdf5' found
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-rca3sha8/netcdf4_bea74f98f91244bda844919dcb89626a/setup.py", line 447, in <module>
        _populate_hdf5_info(dirstosearch, inc_dirs, libs, lib_dirs)
      File "/tmp/pip-install-rca3sha8/netcdf4_bea74f98f91244bda844919dcb89626a/setup.py", line 388, in _populate_hdf5_info
        raise ValueError('did not find HDF5 headers')
    ValueError: did not find HDF5 headers
    reading from setup.cfg...
    
        HDF5_DIR environment variable not set, checking some standard locations ..
    checking /home/pi/include ...
    hdf5 headers not found in /home/pi/include
    checking /usr/local/include ...
    hdf5 headers not found in /usr/local/include
    checking /sw/include ...
    hdf5 headers not found in /sw/include
    checking /opt/include ...
    hdf5 headers not found in /opt/include
    checking /opt/local/include ...
    hdf5 headers not found in /opt/local/include
    checking /opt/homebrew/include ...
    hdf5 headers not found in /opt/homebrew/include
    checking /usr/include ...
    hdf5 headers not found in /usr/include
    ----------------------------------------

[milancurcic]

Thanks for the review and feedback.

Yes, on some less common platforms like IBM Power9 or Raspberry Pi, netCDF4 doesn't have pre-built wheels on PyPI, and in that case, you need to install a system dependency by hand.

And Conda is a 3rd party tool made by a for-profit corp that you need to install manually on any OS.

Neither solution is ideal and each has its pros and cons. Moreover, the differences are more cultural than technical. We need to support both kinds of users because neither is insignificant in numbers.

Let's please end the package manager wars here. The best we can do as a package is to support both package managers as best as we can. For Conda, we already go above and beyond thanks to your effort with conda-forge. And for pip, I'll aim to keep the complexity sufficiently low so that CloudDrift continues to build out of the box on the 3 major platforms.

I added a note about building on less common platforms.

[selipot]

Tested successfully on my laptop with both pip and conda installs.