Docs/improve user documentation

CONTRIBUTING.rst

@@ -88,7 +88,7 @@ Ready to contribute? Here's how to set up `Speasy` for local development.
     $ make lint
     $ make test-all # it will run all tests and run code examples in the docs
 
-    Alternatively, if just want to run quick tests for the current Python version, run::
+    Alternatively, if you just want to run quick tests for the current Python version::
 
     $ make test
     $ make doctest
@@ -110,7 +110,7 @@ Before you submit a pull request, check that it meets these guidelines:
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
+   feature to the list in README.md.
 3. The pull request should work for Python from 3.10 to 3.14. Check
    https://github.com/SciQLop/speasy/actions
    and make sure that the tests pass for all supported Python versions.

README.md

@@ -18,8 +18,8 @@
 Speasy is a free and open-source Python package that makes it easy to find and load space physics data from a variety of
 data sources, whether it is online and public such as [CDAWEB](https://cdaweb.gsfc.nasa.gov/index.html/) and [AMDA](http://amda.irap.omp.eu/),
 or any described archive, local or remote.
-This task, where any science project starts, would seem easy a priori but, considering the very
-diverse array of missions and instrument nowaday available, proves to be one of the major bottleneck,
+Finding and loading data is where any science project starts. It would seem easy a priori but, considering the
+diverse array of missions and instruments available nowadays, it proves to be one of the major bottlenecks,
 especially for students and newcomers.
 Speasy solves this problem by providing a **single, easy-to-use interface to over 70 space missions and 65,000 products**.
 
@@ -28,7 +28,7 @@ Don't want to write code? See our graphical interface [SciQLop](https://github.c
 ## Main features
 
 -   Simple and intuitive API (`spz.get_data(...)` to get them all)
--   Speasy variables are like Pandas DataFrame with seemless conversion to/from it (as long as the shape is compatible)
+-   Speasy variables are like Pandas DataFrames with seamless conversion to/from them (as long as the shape is compatible)
 -   Speasy variables support numpy operations, [see numpy operations example below](#numpy-operations)
 -   Speasy variables filtering and resampling capabilities, [see resampling example below](#resampling)
 -   Local cache to avoid redundant downloads
@@ -82,10 +82,10 @@ ace_mag.plot();
 
 #### Using the dynamic inventory
 
-Where amda is the webservice and imf is the product id you will get with
-this request.
+Where `amda` is the data provider and `imf` is the product ID.
 
-Using the dynamic inventory will produce the same result as the previous example, but it has the advantage of being easier to manipulate, since you can discover available data from your favorite Python environment completion tool, such as IPython or notebooks.
+Using the dynamic inventory produces the same result as the previous example, but lets you discover available data
+through tab-completion in IPython, Jupyter notebooks, or any Python environment that supports it.
 
 
 ```python

docs/index.rst

@@ -49,7 +49,7 @@ Space Physics made EASY
 
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4118780.svg
    :target: https://doi.org/10.5281/zenodo.4118780
-   :alt: Zendoo DOI
+   :alt: Zenodo DOI
 
 .. image:: https://mybinder.org/badge_logo.svg
     :target: https://mybinder.org/v2/gh/SciQLop/speasy/main?labpath=docs/examples
@@ -61,10 +61,10 @@ Space Physics made EASY
 
 
 Speasy is a free and open-source Python package that makes it easy to find and load space physics data from a variety of
-data sources, whether it is online and public such as `CDAWEB <https://cdaweb.gsfc.nasa.gov/index.html/>`__ and `AMDA <http://amda.irap.omp.eu/>`__,
-or any described archive, local or remote.
-This task, where any science project starts, would seem easy a priori but, considering the very
-diverse array of missions and instrument nowaday available, proves to be one of the major bottleneck,
+data sources, whether online and public such as `CDAWEB <https://cdaweb.gsfc.nasa.gov/index.html/>`__ and `AMDA <http://amda.irap.omp.eu/>`__,
+or any local or remote archive.
+Finding and loading data is where any science project starts. It would seem easy a priori but, considering the
+diverse array of missions and instruments available nowadays, it proves to be one of the major bottlenecks,
 especially for students and newcomers.
 Speasy solves this problem by providing a **single, easy-to-use interface to over 70 space missions and 65,000 products**.
 
@@ -92,18 +92,18 @@ Getting data is as simple as:
    :width: 49%
    :alt: ACE IMF data
 
-Where amda is the webservice and imf is the product id you will get with this request.
+Where ``amda`` is the data provider and ``imf`` is the product ID.
 
-Using the dynamic inventory this can be even simpler:
+Using the dynamic inventory, this can be even more discoverable:
 
 .. code-block:: python
 
     import speasy as spz
     amda_tree = spz.inventories.data_tree.amda
     ace_mag = spz.get_data(amda_tree.Parameters.ACE.MFI.ace_imf_all.imf, "2016-6-2", "2016-6-5")
 
-Will produce the exact same result than previous example but has the advantage to be easier to manipulate since you can
-discover available data from your favourite Python environment completion such as IPython or notebooks (might not work from IDEs).
+This produces the same result as the previous example but lets you discover available data
+through tab-completion in IPython, Jupyter notebooks, or any Python environment that supports it.
 
 This also works with `SSCWEB <https://sscweb.gsfc.nasa.gov/>`__, you can easily download trajectories:
 
@@ -140,8 +140,8 @@ Features
 - Can take advantage of SciQLop dedicated proxy as a community backed ultra fast cache
 - Full support of `AMDA <http://amda.irap.omp.eu/>`__ API
 - Can retrieve time-series from `AMDA <http://amda.irap.omp.eu/>`__, `CDAWeb <https://cdaweb.gsfc.nasa.gov/>`__, `CSA <https://csa.esac.esa.int/csa-web/>`__, `SSCWeb <https://sscweb.gsfc.nasa.gov/>`__
-- Can retrieve any data from any local or remote archive with a `simple configuration file <user/direct_archive/direct_archive>`__
-- Also available as [Speasy.jl](https://github.com/SciQLop/Speasy.jl) for Julia users
+- Can retrieve data from any local or remote archive with a :doc:`simple configuration file <user/direct_archive/direct_archive>`
+- Also available as `Speasy.jl <https://github.com/SciQLop/Speasy.jl>`__ for Julia users
 
 Examples
 ========

docs/installation.rst

@@ -8,27 +8,27 @@ Installation
 Stable release
 --------------
 
-To install Space Physics WebServices Client, run this command in your terminal:
+To install Speasy, run this command in your terminal:
 
 .. code-block:: console
 
     $ python -m pip install speasy
     # or
     $ python -m pip install --user speasy
 
-This is the preferred method to install Space Physics WebServices Client, as it will always install the most recent stable release.
+This is the preferred method to install Speasy, as it will always install the most recent stable release.
 
 If you don't have `pip`_ installed, this `Python installation guide`_ can guide
 you through the process.
 
 .. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
+.. _Python installation guide: https://docs.python-guide.org/en/latest/starting/installation/
 
 
 From sources
 ------------
 
-The sources for Space Physics WebServices Client can be downloaded from the `Github repo`_.
+The sources for Speasy can be downloaded from the `Github repo`_.
 
 You can either clone the public repository:
 

docs/user/Uiowa_eph_tool/uiowa_eph_tool.rst

@@ -5,8 +5,8 @@ University of Iowa Cassini Ephemeris Tool
    :maxdepth: 1
 
 
-`UiowaEphTool <https://space.physics.uiowa.edu/~jbg/cas.html>`_ provides trajectories for Cassini, Ulysses, Voyager 1 and Voyager 2 spacecrafts
-in different coordinate systems. It's integration into speasy makes easy to get any available object trajectory on any time range.
+`UiowaEphTool <https://space.physics.uiowa.edu/~jbg/cas.html>`_ provides trajectories for Cassini, Ulysses, Voyager 1, and Voyager 2
+in different coordinate systems. Its integration into Speasy makes it easy to get any available trajectory for any time range.
 
 Basics: Getting data from UiowaEphTool module
 ---------------------------------------------

docs/user/amda/amda.rst

@@ -4,9 +4,10 @@ Automated Multi-Dataset Analysis (AMDA)
 .. toctree::
    :maxdepth: 1
 
-`AMDA <http://amda.irap.omp.eu/>`__ is one of the main data providers handled by speasy. All products are either available using directly the AMDA module or using :meth:`speasy.get_data()`.
-:meth:`speasy.get_data()` usage should be preferred over AMDA module methods since it is more flexible and it's interface is guaranteed to be more stable.
-The following documentation will focus on AMDA module specific usage.
+`AMDA <http://amda.irap.omp.eu/>`__ is one of the main data providers handled by Speasy. All products are available either
+through the AMDA module directly or through :meth:`speasy.get_data()`.
+Using :meth:`speasy.get_data()` should be preferred over AMDA module methods since it is more flexible and its interface is guaranteed to be more stable.
+The following documentation focuses on AMDA module specific usage.
 
 
 Basics: Getting data from AMDA
@@ -66,8 +67,8 @@ Then simply:
     >>> len(mms4_fgm_btot.time)
     57600
 
-2. Second scenario, your are not much familiar with AMDA, then you can simply browse speasy dynamic inventory. In
-the following example, we alias AMDA data tree as amdatree, note that Python completion works and you will be able to discover
+2. Second scenario, you are not familiar with AMDA. You can browse Speasy's dynamic inventory instead. In
+the following example, we alias AMDA's data tree as ``amdatree``. Tab-completion works, so you can discover
 AMDA products directly from your Python terminal or notebook:
 
     >>> import speasy as spz
@@ -204,9 +205,9 @@ Once we have magnetic field measurements inside each cloud, we will as an exampl
     >>> plt.legend() # doctest: +SKIP
     >>> plt.show() # doctest: +SKIP
     >>> # Now let's get MFI data for each cloud
-    >>> b_mfi_coulds = spz.get_data(amda_parameters.Wind.MFI.wnd_mfi_kp.wnd_bmag, Magnetic_Clouds)
+    >>> b_mfi_clouds = spz.get_data(amda_parameters.Wind.MFI.wnd_mfi_kp.wnd_bmag, Magnetic_Clouds)
     >>> # compute mean of B for each cloud and ignore NaNs
-    >>> b_mean_mfi_clouds = [ np.nanmean(cloud.values) for cloud in b_mfi_coulds ]
+    >>> b_mean_mfi_clouds = [ np.nanmean(cloud.values) for cloud in b_mfi_clouds ]
     >>> plt.hist(b_mean_mfi_clouds, label="B mean in Magnetic Clouds (nT)") # doctest: +SKIP
     >>> plt.legend() # doctest: +SKIP
     >>> plt.show() # doctest: +SKIP
@@ -230,8 +231,8 @@ Advanced: AMDA module configuration options
 AMDA user login
 ^^^^^^^^^^^^^^^
 
-Most AMDA features are available without login except user created product from web user interface. You can configure
-speasy to store your AMDA login, from your favourite python terminal:
+Most AMDA features are available without login, except for user-created products from the AMDA web interface. You can configure
+Speasy to store your AMDA credentials:
 
     >>> from speasy import config
     >>> config.amda.username.set('my_username') # doctest: +SKIP
@@ -241,7 +242,7 @@ speasy to store your AMDA login, from your favourite python terminal:
     ('my_username', 'my_password')
 
 
-Then if you correctly typed your login you should be able to list and get user products:
+Once configured, you can list and get user products:
 
     >>> from speasy import amda
     >>> # list user products
@@ -259,12 +260,10 @@ Then if you correctly typed your login you should be able to list and get user p
 AMDA cache retention
 ^^^^^^^^^^^^^^^^^^^^
 
-While parameter download cache is not configurable and relies on product version to decide if local data is up to date
-compared to remote data. Requests like catalogs or time-tables download have a different dedicated cache
-based on duration, by default they will be cached for 15 minutes. As a consequence if a time-table has changed on AMDA servers
-it might take up to the configured duration to see it.
-This cache has been designed with interactive usage of speasy in mind where we want to minimize penalty of running
-multiple times the same command/line in a short amount of time.
+Parameter downloads rely on product version to decide if local data is up to date compared to remote data.
+Catalogs and timetables use a different time-based cache: by default they are cached for 15 minutes.
+If a timetable or catalog has changed on AMDA servers, it may take up to the configured duration before the update is visible.
+This cache is designed for interactive usage where you may run the same command multiple times in a short amount of time.
 
 To change this cache duration value:
 

docs/user/cdaweb/cdaweb.rst

@@ -26,13 +26,13 @@ Once you have found your product, then simply ask CDA module to get data for the
 Specific CDAWeb options
 -----------------------
 
-The CDAWeb module allows to choose the method to get data among 'BEST', 'FILE', 'API', default is 'BEST'.
+The CDAWeb module lets you choose the access method among ``BEST``, ``FILE``, and ``API``. The default is ``BEST``.
 
-* 'BEST' will try to choose the best method between 'FILE' and 'API' for each dataset.
-* 'FILE' will download the data files from the CDAWeb server directly using the `archive` module.
-* 'API' will get the data using the CDAWeb API.
+* ``BEST`` — automatically selects between ``FILE`` and ``API`` for each dataset.
+* ``FILE`` — downloads CDF files directly from the CDAWeb archive.
+* ``API`` — retrieves data through the CDAWeb REST API.
 
-User can specify the method to use to get the data by passing the `method` argument to the `spz.get_data` function.
+You can specify the method by passing the ``method`` argument to ``spz.get_data()``.
 
     >>> import speasy as spz
     >>> # Let's assume you wanted to get Solar Orbiter 'Magnetic field vector in RTN coordinates'
@@ -42,7 +42,7 @@ User can specify the method to use to get the data by passing the `method` argum
     >>> solo_mag_rtn.values.shape
     (1438, 3)
 
-User can also set the default method to use to get the data by setting the `spz.config.cdaweb.preferred_access_method` configuration variable.
+You can also set the default method globally:
 
     >>> import speasy as spz
     >>> spz.config.cdaweb.preferred_access_method.set('BEST')

docs/user/cdpp3dview/cdpp3dview.rst

@@ -5,8 +5,8 @@ CDPP 3DView Data Provider
    :maxdepth: 1
 
 
-`CDPP 3DView <https://3dview.irap.omp.eu/>`_ provides planets, spacecrafts and comets trajectories in different
-coordinate systems. Its integration into speasy makes easy to get trajectory data for various missions
+`CDPP 3DView <https://3dview.irap.omp.eu/>`_ provides planet, spacecraft, and comet trajectories in different
+coordinate systems. Its integration into Speasy makes it easy to get trajectory data for various missions
 on any time range.
 
 Basics: Getting data from Cdpp3dView module

docs/user/configuration.rst

@@ -1,13 +1,16 @@
 Configuration
 =============
 
-Speasy is configured using the config module or setting environment variables or editing an ini file.
-The default location can be found by running:
+Speasy can be configured through the ``config`` module, environment variables, or by editing an INI file directly.
+
+The configuration file is an INI file located in your platform's user config directory under ``speasy/LPP/config.ini``
+(e.g. ``~/.config/speasy/LPP/config.ini`` on Linux, ``~/Library/Application Support/speasy/LPP/config.ini`` on macOS).
+You can also find the exact path programmatically:
 
     >>> import speasy as spz
     >>> print(spz.config.SPEASY_CONFIG_FILE) # doctest: +SKIP
 
-Speasy current configuration can be displayed by running:
+To display the current configuration:
 
     >>> import speasy as spz
     >>> spz.config.show() # doctest: +SKIP
@@ -22,7 +25,7 @@ Disabling data providers
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes you may want to disable some data providers either to speed up Speasy import or because you don't need them.
-This can be done by adding the provider name to the `disabled_providers` list in the configuration file.
+This can be done by adding the provider name to the ``disabled_providers`` list in the configuration file.
 
 For example, to disable AMDA and CDAWeb, add the following to the configuration file:
 
@@ -39,7 +42,8 @@ Or from Python:
 Cache section
 -------------
 
-You can configure the cache location and maximum size by editing the `cache` section of the configuration file.
+You can configure the cache location and maximum size (in bytes) by editing the ``cache`` section of the configuration file.
+The default maximum cache size is 20 GB (20e9 bytes).
 
 .. code-block:: ini
 
@@ -56,5 +60,4 @@ Or from Python:
 Connecting behind an HTTP proxy
 --------------------------------
 
-If you are behind an HTTP proxy, Speasy will automatically use the HTTP_PROXY environment variable.
-Note that you won't be able to access the CSA database until https://github.com/astropy/astroquery/issues/3228 is resolved.
+Speasy automatically uses the ``HTTP_PROXY`` and ``HTTPS_PROXY`` environment variables if they are set.

docs/user/csa/csa.rst

@@ -5,8 +5,8 @@ Cluster Science Archive (CSA)
    :maxdepth: 1
 
 The `Cluster Science Archive (CSA) <https://csa.esac.esa.int/csa-web/>`_ provides access to all science and support data
-of the on-going Cluster (2000- ) and Double Star (2004-2008) missions. It's integration into speasy makes easy to get any
-public data from the **CSA** handling both webservice **API** and **ISTP** **CDF** files read.
+from the ongoing Cluster (2000–present) and Double Star (2004–2008) missions. Its integration into Speasy makes it easy to get any
+public data from the CSA, handling both the webservice API and ISTP CDF file formats.
 
 Basics: Getting data from CSA module
 ------------------------------------