work on documentation

aprofiles/emc.py

@@ -13,7 +13,7 @@
 class EMCData:
     """
     Class for computing the *Extinction to Mass Coefficient* for a given aerosol type.
-    This class calls the :func:`get_emc()` method.
+    This class calls the [`get_emc()`](#aprofiles.emc.EMCData.get_emc) method.
 
     Attributes:
        `aer_type` ({'dust', 'volcanic_ash', 'biomass_burning', 'urban'}): aerosol type.
@@ -79,71 +79,123 @@ def __init__(self, aer_type: str, wavelength: float, method: str = "mortier_2013
 
     def get_emc(self):
         """
-        Calculates the Extinction to Mass Coefficient for a given type of particles assuming with prescribed size distribution shape (the amplitude is unknown), density, and using the `Mie theory <https://miepython.readthedocs.io>`_ to calculate the extinction efficiency.
-
+        Calculates the Extinction to Mass Coefficient for a given type of particles, assuming a prescribed size distribution shape (with unknown amplitude), density, and using [Mie theory](https://miepython.readthedocs.io) to calculate the extinction efficiency.
+        
         Returns:
             (EMCData): with additional attributes:
-
+            
                 - `nsd` (1D Array): Number Size Distribution
                 - `vsd` (1D Array): Volume Size Distribution
-                - `radius` (1D Array): Radius, in µm
+                - `radius` (1D Array): Radius in µm
                 - `x` (1D Array): Size parameter (unitless)
-                - `conv_factor` (float): Conversion factor, in m
-                - `emc` (float): Extinction to Mass Coefficient, in m2.g-1
+                - `conv_factor` (float): Conversion factor in m
+                - `emc` (float): Extinction to Mass Coefficient in m².g⁻¹
+
+       !!! note
+            For a population of particles, the extinction coefficient $\sigma_{ext}$ (m⁻¹) can be written as follows:
 
-        .. note::
-            For a population of particles, the extinction coefficient :math:`\sigma_{ext}` (m-1) can be written as follwowing:
+            $$
+            \sigma_{ext} = \int_{r_{min}}^{r_{max}} N(r) Q_{ext}(m, r, \lambda) \pi r^2 dr
+            $$
 
-            :math:`\sigma_{ext} = \int_{r_{min}}^{r_{max}}N(r)Q_{ext}(m,r,\lambda) \pi r^2 dr`
+            where $Q_{ext}$ is the `extinction efficiency` and $N(r)$ is the `Number Size Distribution` (NSD).
 
-            with :math:`Q_{ext}`, the `extinction efficiency` and :math:`N(r)` the `Number Size Distribution` (NSD).
+            $Q_{ext}$ varies with the refractive index, $m$, the wavelength, $\lambda$, and can be calculated for spherical particles using Mie theory.
 
-            :math:`Q_{ext}` varies with the refractive index, :math:`m`, the wavelength, :math:`\lambda` and can be calculated for spherical particles with the Mie therory.
+            The total aerosol mass concentration $M_0$ (µg.m⁻³) can be expressed as:
 
-            Total aerosol mass concentration :math:`M_0` (µg.m-3) can be written as:
+            $$
+            M_0 = \int_{r_{min}}^{r_{max}} M(r) dr
+            $$
 
-            :math:`M_0 = \int_{r_{min}}^{r_{max}}{M(r)dr}` where :math:`M(r)` is the mass size distribution (MSD).
+            where $M(r)$ is the mass size distribution (MSD).
 
-            This equation can be written, using the relation between NSD and MSD, as:
+            This can be rewritten in terms of NSD and MSD as:
 
-            :math:`M_0 = \int_{r_{min}}^{r_{max}}{\\frac{4\pi r^3}{3} \\rho N(r) dr}`
+            $$
+            M_0 = \int_{r_{min}}^{r_{max}} \\frac{4\pi r^3}{3} \\rho N(r) dr
+            $$
 
-            where :math:`\\rho` is the particles `density` (kg.m-3).
+            where $\\rho$ is the particle density (kg.m⁻³).
 
-            By normalizing the NSD with respect to the fine mode (:math:`N(r) = N_0 N_1(r)`), the combination of the previous equations leads to:
+            By normalizing the NSD with respect to the fine mode ($N(r) = N_0 N_1(r)$), we arrive at:
 
-            :math:`M_0 = \sigma_{ext} \\rho \\frac{4}{3} \\frac{\int_{r_{min}}^{r_{max}} N_1(r) r^3 dr}{\int_{r_{min}}^{r_{max}} N_1(r) Q_{ext}(m,r,\lambda) r^2 dr}`
+            $$
+            M_0 = \sigma_{ext} \\rho \\frac{4}{3} \\frac{\int_{r_{min}}^{r_{max}} N_1(r) r^3 dr}{\int_{r_{min}}^{r_{max}} N_1(r) Q_{ext}(m, r, \lambda) r^2 dr}
+            $$
 
-            By commodity, we define the `conversion factor` (in m) as :math:`c_v = \\frac{4}{3} \\frac{\int_{r_{min}}^{r_{max}} N_1(r) r^3 dr}{\int_{r_{min}}^{r_{max}} N_1(r) Q_{ext}(m,r,\lambda) r^2 dr}`
+            We define the `conversion factor` (in m) as:
 
-            so the previous equation can be simplified: :math:`M_0 = \sigma_{ext} \\rho c_v`
+            $$
+            c_v = \\frac{4}{3} \\frac{\int_{r_{min}}^{r_{max}} N_1(r) r^3 dr}{\int_{r_{min}}^{r_{max}} N_1(r) Q_{ext}(m, r, \lambda) r^2 dr}
+            $$
 
-            Finally, the `Extinction to Mass Coefficient` (EMC, also called `mass extinction cross section`, usually provided in m2.g-1) is defined as the ratio between :math:`\sigma_{ext}` and :math:`M_0`:
+            Thus, the equation simplifies to:
 
-            :math:`EMC = \\frac{\sigma_{ext}}{M_0} = \\frac{1}{\\rho c_v}`
+            $$
+            M_0 = \sigma_{ext} \\rho c_v
+            $$
 
-            with :math:`\\rho` being expressed in (g.m-3).
+            Finally, the `Extinction to Mass Coefficient` (EMC, also called `mass extinction cross section`, usually in m².g⁻¹) is defined as:
+
+            $$
+            EMC = \\frac{\sigma_{ext}}{M_0} = \\frac{1}{\\rho c_v}
+            $$
+
+            with $\\rho$ expressed in g.m⁻³.
 
             
-            .. table:: Conversion Factors and EMC calculated for the main aerosol types
-                :widths: auto
-
-                +-----------------+------------------------+------------------+
-                | Aerosol Type    | Conversion Factor (µm) | EMC (m2.g-1)     |
-                |                 +-----------+------------+--------+---------+
-                |                 | 532 nm    | 1064 nm    | 532 nm | 1064 nm |
-                +=================+===========+============+========+=========+
-                | Urban           | 0.31      | 1.92       | 1.86   | 0.31    |
-                +-----------------+-----------+------------+--------+---------+
-                | Desert dust     | 0.68      | 1.04       | 0.58   | 0.38    |
-                +-----------------+-----------+------------+--------+---------+
-                | Biomass burning | 0.26      | 1.28       | 3.30   | 0.68    |
-                +-----------------+-----------+------------+--------+---------+
-                | Volcanic ash    | 0.62      | 0.56       | 0.62   | 0.68    |
-                +-----------------+-----------+------------+--------+---------+
+            <table>
+                <thead>
+                    <tr>
+                        <th>Aerosol Type</th>
+                        <th colspan=2>Conversion Factor (µm)</th>
+                        <th colspan=2>EMC (m².g⁻¹) </th>
+                    </tr>
+                    <tr>
+                        <th></th>
+                        <th>532 nm</th>
+                        <th>1064 nm</th>
+                        <th>532 nm</th>
+                        <th>1064 nm</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <tr>
+                        <td>Urban</td>
+                        <td>0.31</td>
+                        <td>1.92</td>
+                        <td>1.86</td>
+                        <td>0.31</td>
+                    </tr>
+                    <tr>
+                        <td>Desert dust</td>
+                        <td>0.68</td>
+                        <td>1.04</td>
+                        <td>0.58</td>
+                        <td>0.38</td>
+                    </tr>
+                    <tr>
+                        <td>Biomass burning</td>
+                        <td>0.26</td>
+                        <td>1.28</td>
+                        <td>3.30</td>
+                        <td>0.68</td>
+                    </tr>
+                    <tr>
+                        <td>Volcanic ash</td>
+                        <td>0.62</td>
+                        <td>0.56</td>
+                        <td>0.62</td>
+                        <td>0.68</td>
+                    </tr>
+                </tbody>
+                <caption>Conversion Factors and EMC calculated for the main aerosol types</caption>
+            </table>
 
         """
 
+
         def _compute_conv_factor(nsd, qext, radius):
             """Compute Conversion Factor for a given Size Distribution and Efficiency
 
@@ -202,7 +254,7 @@ def _compute_conv_factor(nsd, qext, radius):
 
     def plot(self, show_fig=True):
         """
-        Plot main information of an instance of the (EMCData): class.
+        Plot main information of an instance of the [`EMCData`](#aprofiles.emc.EMCData) class.
 
         Example:
             ```python
@@ -214,11 +266,7 @@ def plot(self, show_fig=True):
             emc.plot()
             ```
 
-            .. figure:: ../../docs/assets/images/volcanic_ash-emc.png
-                :scale: 80 %
-                :alt: volcanic ash properties
-
-                Volcanic Ash particles properties used for EMC calculation.
+            ![Volcanic Ash particles properties used for EMC calculation](../../assets/images/volcanic_ash-emc.png)
         """
         fig, ax = plt.subplots(1, 1, figsize=(6, 6))
 

docs/api.md

@@ -1,8 +1,6 @@
----
-title: API
----
+# Overview
 
-![image](assets/images/cogs-solid.svg){.awesome-svg .awesome-svg}
+:material-api:
 
 Documentation of the core API of [aprofiles](/).
 

docs/api/data_classes.md

@@ -1,67 +1,40 @@
----
-title: Data Classes
----
+# Data Classes
 
-ProfilesData
-============
+## ProfilesData
 
-The (aprofiles.profiles.ProfilesData):
-class contains profiles data information. Most of the information can be
-found in the [data]{.title-ref} attribute, which is a
-(xarray.Dataset):. Detection and
-retrieval methods might add information as :additional
-(xarray.DataArray):).
+The [`ProfilesData`](#profilesdata) class contains profile data information. Most of the information can be found in the `data` attribute, which is an [`xarray.Dataset`](https://xarray.pydata.org/en/stable/generated/xarray.Dataset.html). Detection and retrieval methods might add information as additional [`xarray.DataArray`](https://xarray.pydata.org/en/stable/generated/xarray.DataArray.html).
 
 ::: aprofiles.profiles
 
-Aeronet
-=======
+## Aeronet
 
 Not implemented yet.
 
 ::: aprofiles.aeronet
 
-Rayleigh
-========
+## Rayleigh
 
-The (aprofiles.rayleigh.RayleighData):
-class is used for producing Rayleigh profiles in a standard atmosphere.
+The [`RayleighData`](#rayleighdata) class is used for producing Rayleigh profiles in a standard atmosphere.
 
 ::: aprofiles.rayleigh
 
-Size Distribution
-=================
+## Size Distribution
 
-The size distribution module is used to produce volume and number size
-distribution of a population of particles for a given type. The values
-describing the size distribution for the different aerosol types are
-taken from the literature:
+The size distribution module is used to produce volume and number size distributions of a population of particles for a given type. The values describing the size distribution for different aerosol types are taken from the literature:
 
--   `dust`, `biomass_burning`, and `urban` aerosols[^1]
--   `volcanic_ash`[^2]
-
-Aerosol properties are defined in
-[`config/aer_properties.json`](../../aprofiles/config/aer_properties.json){: .title-ref role="download"}
+- `dust`, `biomass_burning`, and `urban` aerosols[^1]
+- `volcanic_ash`[^2]
 
+Aerosol properties are defined in [`config/aer_properties.json`](../../aprofiles/config/aer_properties.json){: .title-ref role="download"}
 
 ::: aprofiles.size_distribution
 
-Extinction to Mass Coefficient
-==============================
+## Extinction to Mass Coefficient
 
-The (aprofiles.emc.EMCData): class is
-used for computing an [Extinction to Mass Coefficient]{.title-ref} for a
-given aerosol type.
+The [`EMCData`](#emcdata) class is used for computing an *Extinction to Mass Coefficient* for a given aerosol type.
 
 ::: aprofiles.emc
 
-[^1]: Dubovik, O., Holben, B., Eck, T. F., Smirnov, A., Kaufman, Y. J.,
-    King, M. D., \... & Slutsker, I. (2002). Variability of absorption
-    and optical properties of key aerosol types observed in worldwide
-    locations. Journal of the atmospheric sciences, 59(3), 590-608.
+[^1]: Dubovik, O., Holben, B., Eck, T. F., Smirnov, A., Kaufman, Y. J., King, M. D., ... & Slutsker, I. (2002). Variability of absorption and optical properties of key aerosol types observed in worldwide locations. *Journal of the Atmospheric Sciences*, 59(3), 590-608.
 
-[^2]: Mortier, A., Goloub, P., Podvin, T., Deroo, C., Chaikovsky, A.,
-    Ajtai, N., \... & Derimian, Y. (2013). Detection and
-    characterization of volcanic ash plumes over Lille during the
-    Eyjafjallajökull eruption. Atmospheric Chemistry and Physics, 13(7),
-    3705-3720.
+[^2]: Mortier, A., Goloub, P., Podvin, T., Deroo, C., Chaikovsky, A., Ajtai, N., ... & Derimian, Y. (2013). Detection and characterization of volcanic ash plumes over Lille during the Eyjafjallajökull eruption. *Atmospheric Chemistry and Physics*, 13(7), 3705-3720.

docs/api/detection.md

@@ -1,29 +1,21 @@
----
-title: Detection
----
+# Detection
 
-The following functions are methods from the class
-`aprofiles.profiles.ProfilesData`{.interpreted-text role="class"}.
+The following functions are methods from the class [`ProfilesData`](../data_classes/#profilesdata).
 
-Fog or Condensation
-===================
+## Fog or Condensation
 
-This method allows for the detection of fog or condensation in single
-profiles.
+This method allows for the detection of fog or condensation in single profiles.
 
 ::: aprofiles.detection.foc
 
-Clouds
-======
+## Clouds
 
 This method allows for the detection of clouds in single profiles.
 
 ::: aprofiles.detection.clouds
 
-Planetary Boundary Layer
-========================
+## Planetary Boundary Layer
 
-This method allows for tge tracking of the PBL height in single
-profiles.
+This method allows for the tracking of the Planetary Boundary Layer (PBL) height in single profiles.
 
 ::: aprofiles.detection.pbl

docs/api/plotting.md

@@ -1,31 +1,19 @@
----
-title: Plotting
----
+# Plotting
 
-Image
-=====
+## Image
 
-This module is used to plot an image (time, altitude) a given variable
-of an instance of the
-`aprofiles.profiles.ProfilesData`{.interpreted-text role="class"} class.
+This module is used to plot an image (time, altitude) for a given variable of an instance of the [`ProfilesData`](../data_classes/#profilesdata) class.
 
 ::: aprofiles.plot.image
 
-Profile
-=======
+## Profile
 
-This module is used to plot a single profile for, a given
-`numpy.datetime64`{.interpreted-text role="class"}, of a given variable
-of an instance of the
-`aprofiles.profiles.ProfilesData`{.interpreted-text role="class"} class.
+This module is used to plot a single profile for a given [`numpy.datetime64`](https://numpy.org/doc/stable/reference/arrays.datetime.html), of a given variable of an instance of the [`ProfilesData`](../data_classes/#profilesdata) class.
 
 ::: aprofiles.plot.profile
 
-Time Series
-===========
+## Time Series
 
-This module is used to plot a time series of a given variable of an
-instance of the `aprofiles.profiles.ProfilesData`{.interpreted-text
-role="class"} class.
+This module is used to plot a time series of a given variable of an instance of the [`ProfilesData`](../data_classes/#profilesdata) class.
 
 ::: aprofiles.plot.timeseries

docs/api/reading.md

@@ -1,8 +1,5 @@
----
-title: Reader
----
+# Reading
 
-The `Reader`{.interpreted-text role="ref"} module includes classes for
-reading profiles (NetCDF) and Aeronet (txt) data.
+The [`Reader`](#aprofiles.reader) module includes classes for reading profiles (NetCDF) and Aeronet (txt) data.
 
 ::: aprofiles.reader