Merge branch 'main' into add-plotting-docs

Author: Iqbal-dev12

.github/workflows/docs.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
 
 jobs:
   deploy:
@@ -24,7 +25,8 @@ jobs:
     - name: Install MkDocs and dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install mkdocs mkdocs-macros-plugin requests
+        pip install -r pyproject.toml --extra docs
+
 
     - name: Build docs
       run: mkdocs build

cdippy/ncstats.py

@@ -4,22 +4,24 @@
 
 
 class NcStats(StnData):
-    """For a given station, produces data availability.
+    """Produces data availability statistics for a given station.
 
-    There are methods to return counts for the entire station record to be
-    used diretly by a web app, and there are methods to save to disk availabililty
-    counts (e.g. xyz counts) for individual nc files. In that case updates
-    to totals would be calculated by re-summarizing any files that have changed
-    and adding up all the files to produce new totals.
+    This class provides methods to:
+        * Return counts for the entire station record, intended for use by web applications.
+        * Save availability counts (e.g., xyz counts) for individual NetCDF files.
+          Updates to totals are calculated by re-summarizing any files that have changed
+          and aggregating all files to produce new totals.
     """
 
     QC_flags = ["waveFlagPrimary", "sstFlagPrimary", "gpsStatusFlags"]
 
     def __init__(self, stn: str, data_dir: str = None):
-        """
-        PARAMETERS: See StnData
-        """
+        """Initializes an NcStats instance.
 
+        Args:
+            stn (str): Station identifier.
+            data_dir (str, optional): Path to the data directory. Defaults to None.
+        """
         StnData.__init__(self, stn, data_dir)
 
         self.date_modifieds = {}
@@ -28,14 +30,26 @@ def __init__(self, stn: str, data_dir: str = None):
         self.pub_set = "all"
 
     def make_stats(self) -> dict:
-        """Returns various statistics off the given station."""
+        """Computes station-level statistics.
+
+        Returns:
+            dict: A dictionary containing:
+                - "flag_counts" (dict): Flag count summaries for the station.
+                - "deployments" (dict): Deployment summary statistics.
+        """
         result = {}
         result["flag_counts"] = self.flag_counts()
         result["deployments"] = self.deployment_summary()
         return result
 
     def deployment_summary(self) -> dict:
-        """Returns deployment summary statistics."""
+        """Generates deployment summary statistics.
+
+        Returns:
+            dict: A dictionary containing:
+                - Deployment IDs as keys, with values containing start and end coverage times.
+                - "number_of_deployments" (int): The number of deployments.
+        """
         self.load_nc_files()
         result = {}
         dep_cnt = 0
@@ -54,11 +68,26 @@ def deployment_summary(self) -> dict:
         return result
 
     def load_nc_files(self, types: list = ["realtime", "historic", "archive"]) -> dict:
-        """Returns netCDF4 objects of a station's netcdf files"""
+        """Loads NetCDF files for the station.
+
+        Args:
+            types (list, optional): List of file categories to load. Defaults to
+                ["realtime", "historic", "archive"].
+
+        Returns:
+            dict: Dictionary of NetCDF file objects keyed by filename.
+        """
         self.nc_files = self.get_nc_files(types)
 
     def load_file(self, nc_filename: str):
-        """Sets self.nc for a given nc_filename"""
+        """Loads a specific NetCDF file into the instance.
+
+        Args:
+            nc_filename (str): Filename of the NetCDF file.
+
+        Sets:
+            self.nc: Loaded NetCDF file object.
+        """
         if nc_filename in self.nc_files:
             self.nc = self.nc_files[nc_filename]
         else:
@@ -78,7 +107,15 @@ def nc_file_summaries(self) -> dict:
         return result
 
     def nc_file_summary(self, nc_filename: str) -> dict:
-        """Returns statistical summaries given an nc file name."""
+        """Computes a summary for a given NetCDF file.
+
+        Args:
+            nc_filename (str): Name of the NetCDF file.
+
+        Returns:
+            dict: Summary statistics for the file, including:
+                - "flag_counts" (dict): Flag count statistics.
+        """
         if self.nc is None:
             self.load_file(nc_filename)
         result = {}
@@ -87,7 +124,17 @@ def nc_file_summary(self, nc_filename: str) -> dict:
         return result
 
     def flag_counts(self, QC_flags: list = None) -> dict:
-        """Returns pandas dataframe of counts of flag variables for the entire station record."""
+        """Computes counts of flag variables for the entire station record.
+
+        Args:
+            QC_flags (list, optional): List of quality-control flag variable names.
+                Defaults to `self.QC_flags`.
+
+        Returns:
+            dict: A dictionary containing:
+                - "totals" (dict[str, pandas.DataFrame]): Total counts per flag.
+                - "by_month" (dict[str, pandas.DataFrame]): Monthly counts per flag.
+        """
         result = {"totals": {}, "by_month": {}}
         if not QC_flags:
             QC_flags = self.QC_flags
@@ -100,11 +147,26 @@ def flag_counts(self, QC_flags: list = None) -> dict:
         return result
 
     def total_count(self, cat_var) -> pd.DataFrame:
-        """Returns count totals for a given flag variable."""
+        """Counts totals for a given categorical flag variable.
+
+        Args:
+            cat_var (pandas.Categorical): Categorical flag variable.
+
+        Returns:
+            pandas.DataFrame: DataFrame with counts grouped by category.
+        """
         return pd.DataFrame({"cnt": cat_var}).groupby(cat_var).count()
 
     def by_month_count(self, cat_var, dim: str) -> pd.DataFrame:
-        """Returns pandas dataframe of Counts by month for a given flag variable."""
+        """Counts observations by month for a given flag variable.
+
+        Args:
+            cat_var (pandas.Categorical): Categorical flag variable.
+            dim (str): Dimension name prefix for the time variable.
+
+        Returns:
+            pandas.DataFrame: DataFrame with counts grouped by month and flag value.
+        """
         df = pd.DataFrame(
             {"cnt": cat_var}, index=pd.to_datetime(self.data[dim + "Time"], unit="s")
         )

docs/dev_guide/contribute.md

@@ -9,8 +9,8 @@ Thank you for considering making a contribution to CDIPpy! We welcome all types
 ## Setting up your git workflow
 This project uses a fork-and-pull-request workflow. You will need to make your [fork](https://github.com/cdipsw/CDIPpy/fork) of the repository to work in, and submit changes to CDIPpy via pull request. To set up your workflow, follow these instructions:
 
-1. Fork the respository at [https://github.com/cdipsw/CDIPpy/fork](https://github.com/cdipsw/CDIPpy/fork)
-2. Clone the repository from  your fork `git clone https://github.com/{your_github_username}/CDIPpy.git` - this will add your own fork as your `origin` remote repo. *Note: If you already have the main fork cloned, skip to the next step and follow instuctions to add your fork as another remote.*
+1. Fork the repository at [https://github.com/cdipsw/CDIPpy/fork](https://github.com/cdipsw/CDIPpy/fork)
+2. Clone the repository from  your fork `git clone https://github.com/{your_github_username}/CDIPpy.git` - this will add your own fork as your `origin` remote repo. *Note: If you already have the main fork cloned, skip to the next step and follow instructions to add your fork as another remote.*
 3. Add the main fork as another remote (or your fork, if you cloned from the main fork). This will allow you to pull latest code from the main fork, but push your own development to your own fork:  
 ```bash
 git add remote cdip https://github.com/cdipsw/CDIPpy.git
@@ -26,21 +26,21 @@ git checkout main # make sure this is cdip/main not your fork
 git pull
 git checkout -b example-branch
 ```
-This will create a new branch called `example-branch` based on the lastest commit to `main`. Now you can start making your changes.  
+This will create a new branch called `example-branch` based on the latest commit to `main`. Now you can start making your changes.  
 
 Any changes you plan to contribute should be sure to follow the project's style guide, testing structure, and be up-to-date with documentation.
 
 ### linting
-First you'll need to make sure your code style matches the rest of `cdippy` by using the `flake8` linter to check for adherance to the [PEP8](https://peps.python.org/pep-0008/) style guide:  
+First you'll need to make sure your code style matches the rest of `cdippy` by using the `flake8` linter to check for adherence to the [PEP8](https://peps.python.org/pep-0008/) style guide:  
 ```bash
 flake8 .
 ```
-If this commnad is successful, your style is up to date! Otherwise, the output will indicate where in the project the style is not compliant. You can manually fix these style deviations, or use  a tool like [`black`](https://black.readthedocs.io/en/stable/) to autolint: 
+If this command is successful, your style is up to date! Otherwise, the output will indicate where in the project the style is not compliant. You can manually fix these style deviations, or use  a tool like [`black`](https://black.readthedocs.io/en/stable/) to autolint: 
 ```bash
 black .  
 ```
 
-This project also provides a [`pre-commit`](https://pre-commit.com/) hook to manage style for you autmatically on every `git commit`. From  the porject root:
+This project also provides a [`pre-commit`](https://pre-commit.com/) hook to manage style for you automatically on every `git commit`. From  the project root:
 ```bash
 pre-commit install
 ```

docs/dev_guide/index.md

@@ -15,13 +15,13 @@ You'll specifically want to look at configuring credentials with [https](https:/
 ## Install with dev tools
 It is recommended to us [`uv`](https://docs.astral.sh/uv/) to manage you development environment for this project, but other package managers will likely work as well. This documentation provides instructions for using `uv`.
 
-Navigate to the project root dirctory ('CDIPpy/') and run the following:
+Navigate to the project root directory ('CDIPpy/') and run the following:
 ``` bash
->>> pip install uv  # install uv pacakge manager
->>> uv sync  # create a virtual envionment at CDIPpy/.venv/, install the source code, its runtime dependencies and it's dev dependencies defined in pyproject.toml.
+>>> pip install uv  # install uv package manager
+>>> uv sync  # create a virtual environment at CDIPpy/.venv/, install the source code, its runtime dependencies and it's dev dependencies defined in pyproject.toml.
 >>> source .venv/bin/activate  # activate the environment
 ```
-To exclude the development dpendancies, you can run `uv sync --no-dev`.
+To exclude the development dependencies, you can run `uv sync --no-dev`.
 
 ### testing
 You can check that your dev installation was successful by running unit tests from the root directory: `python -m unittest discover`.  
@@ -30,6 +30,6 @@ This runs every test in the library; you should see all successful tests.
 Learn more about running specific tests or subsets from the [`unittest` docs](https://docs.python.org/3/library/unittest.html).
 
 ### linting
-This library uses `flake8` to check for adherance to the [PEP8](https://peps.python.org/pep-0008/) style guide. To check whether your code is compliant with the project style, run `flake8 .` from the project root.  You can fix problems manually, or use a tool like [`black`](https://black.readthedocs.io/en/stable/) to autolint: `black .`.
+This library uses `flake8` to check for adherence to the [PEP8](https://peps.python.org/pep-0008/) style guide. To check whether your code is compliant with the project style, run `flake8 .` from the project root.  You can fix problems manually, or use a tool like [`black`](https://black.readthedocs.io/en/stable/) to autolint: `black .`.
 
-This project also provides a [`pre-commit`](https://pre-commit.com/) hook to manage style for you autmatically on every `git commit`. To install it, run `pre-commit install` from the project root - this will use `black` and `flake` to autolint and check any changes you make for style before committing them to the repository.
+This project also provides a [`pre-commit`](https://pre-commit.com/) hook to manage style for you automatically on every `git commit`. To install it, run `pre-commit install` from the project root - this will use `black` and `flake` to autolint and check any changes you make for style before committing them to the repository.

docs/index.md

@@ -4,7 +4,7 @@ CDIPpy is python library for navigating and accessing products provided by the [
 A goal of publishing this library as an open source, contributable package is to foster closer collaboration between CDIP and the community of users.
 
 ## Navigating these docs
-The CDIP user community spans a brooad expertise and vastly different backgrounds in python development and usage - use the following guidelines to determine where to start in the documentation:  
+The CDIP user community spans a broad expertise and vastly different backgrounds in python development and usage - use the following guidelines to determine where to start in the documentation:  
 
 * If you are relatively comfortable working with python, visit the [Quickstart Guide](quickstart.md).
 * If you would like more explicit, step-by-step instructions for:

docs/quickstart.md

@@ -39,7 +39,7 @@ To view the coverage report:
 Contributions are welcome and should be merged via pull request on the `main` branch from a forked repository. Before a PR can be merged, it needs to pass the following checks:
 
 * all tests passed
-* coverage >= threshhold
+* coverage >= threshold
 * passes [`flake8`](https://flake8.pycqa.org/en/latest/) linter
 * there must be at least one reviewer approval
 * a CLA must be signed by the contributor, if this is their first commit

pyproject.toml

@@ -29,6 +29,15 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [dependency-groups]
+docs = [
+    "mkdocs",
+    "mkdocs-jupyter",
+    "mkdocs-macros-plugin",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "mkdocs-material",
+]
+
 dev = [
     "black",
     "coverage",
@@ -39,7 +48,6 @@ dev = [
     "mkdocs-material",
     "mkdocstrings[python]",
     "mkdocs-material",
-    "mkdocstrings[python]",
     "nbval",
     "pre-commit",
     "pytest",