refactor: restructure project layout and improve documentation (#107)

refactor: restructure project layout and improve documentation

- migrate to pyproject.toml and remove conda-based setup
- move package source to `src/` and update CI workflows
- switch documentation format from reStructuredText to Markdown
- add and update docstrings using Google style, with examples
- integrate MkDocs with new workflow and improve README
- remove outdated files (e.g. ReadTheDocs config, old notebooks)

ref: #106

Author: MAfarrag

.github/workflows/github-pages-mkdocs.yml

@@ -0,0 +1,99 @@
+name: Deploy MkDocs
+
+permissions:
+  contents: write
+  pages: write
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '**'  # Match all branches for pull requests
+  release:
+      types:
+        - published
+
+jobs:
+  deploy-pr:
+      if: github.event_name == 'pull_request'
+      runs-on: ubuntu-latest
+      steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          pip install .[docs]
+
+      - name: Deploy to GitHub Pages (Pull Request)
+        env:
+          ACTIONS_DEPLOY_TOKEN: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+        run: |
+          git config --global user.name '${{ github.actor }}'
+          git config --global user.email '${{ github.actor }}@users.noreply.github.com'
+
+          mike deploy --push develop
+
+  deploy-main:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        pip install .[docs]
+
+    - name: Deploy to GitHub Pages (Main)
+      env:
+        ACTIONS_DEPLOY_TOKEN: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+      run: |
+        git config --global user.name '${{ github.actor }}'
+        git config --global user.email '${{ github.actor }}@users.noreply.github.com'
+        mike deploy --push main
+        mike set-default --push main
+
+  deploy-release:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+          pip install .[docs]
+
+    - name: Set release notes tag
+      run: |
+        export RELEASE_TAG_VERSION=${{ github.event.release.tag_name }}
+        echo "RELEASE_TAG_VERSION=${RELEASE_TAG_VERSION}" >> $GITHUB_ENV
+
+    - name: Deploy to GitHub Pages
+      env:
+        ACTIONS_DEPLOY_TOKEN: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+      run: |
+        git config --global user.name '${{ github.actor }}'
+        git config --global user.email '${{ github.actor }}@users.noreply.github.com'
+        mike deploy --push --update-aliases ${RELEASE_TAG_VERSION} latest
+        mike set-default --push latest

.readthedocs.yml

@@ -1,15 +1,20 @@
-[![Python Versions](https://img.shields.io/pypi/pyversions/statista.png)](https://img.shields.io/pypi/pyversions/statista)
+# Statista - Advanced Statistical Analysis Package
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/statista.svg)](https://pypi.org/project/statista/)
+[![PyPI version](https://badge.fury.io/py/statista.svg)](https://badge.fury.io/py/statista)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/statista.svg)](https://anaconda.org/conda-forge/statista)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Documentation Status](https://readthedocs.org/projects/statista/badge/?version=latest)](https://statista.readthedocs.io/en/latest/?badge=latest)
+[![codecov](https://codecov.io/gh/Serapieum-of-alex/statista/branch/main/graph/badge.svg?token=GQKhcj2pFK)](https://codecov.io/gh/Serapieum-of-alex/statista)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
-[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/MAfarrag/earth2observe.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/MAfarrag/earth2observe/context:python)
-[![Total alerts](https://img.shields.io/lgtm/alerts/g/MAfarrag/earth2observe.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/MAfarrag/earth2observe/alerts/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/Serapieum-of-alex/statista)](https://github.com/Serapieum-of-alex/statista/commits/main)
+[![GitHub issues](https://img.shields.io/github/issues/Serapieum-of-alex/statista)](https://github.com/Serapieum-of-alex/statista/issues)
+[![GitHub stars](https://img.shields.io/github/stars/Serapieum-of-alex/statista)](https://github.com/Serapieum-of-alex/statista/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/Serapieum-of-alex/statista)](https://github.com/Serapieum-of-alex/statista/network/members)
 
+## Overview
 
-[![codecov](https://codecov.io/gh/Serapieum-of-alex/statista/branch/main/graph/badge.svg?token=GQKhcj2pFK)](https://codecov.io/gh/Serapieum-of-alex/statista)
-![GitHub last commit](https://img.shields.io/github/last-commit/MAfarrag/statista)
-![GitHub forks](https://img.shields.io/github/forks/MAfarrag/statista?style=social)
-![GitHub Repo stars](https://img.shields.io/github/stars/MAfarrag/statista?style=social)
-
+**Statista** is a comprehensive Python package for statistical analysis, focusing on probability distributions, extreme value analysis, and sensitivity analysis. It provides robust tools for researchers, engineers, and data scientists working with statistical models, particularly in hydrology, climate science, and risk assessment.
 
 Current release info
 ====================
@@ -18,62 +23,121 @@ Current release info
 | --- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| --- | --- |
 | [![Conda Recipe](https://img.shields.io/badge/recipe-statista-green.svg)](https://anaconda.org/conda-forge/statista) | [![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/statista.svg)](https://anaconda.org/conda-forge/statista) [![Downloads](https://pepy.tech/badge/statista)](https://pepy.tech/project/statista) [![Downloads](https://pepy.tech/badge/statista/month)](https://pepy.tech/project/statista)  [![Downloads](https://pepy.tech/badge/statista/week)](https://pepy.tech/project/statista)  ![PyPI - Downloads](https://img.shields.io/pypi/dd/statista?color=blue&style=flat-square) | [![Conda Version](https://img.shields.io/conda/vn/conda-forge/statista.svg)](https://anaconda.org/conda-forge/statista) [![PyPI version](https://badge.fury.io/py/statista.svg)](https://badge.fury.io/py/statista) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/statista/badges/version.svg)](https://anaconda.org/conda-forge/statista) | [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/statista.svg)](https://anaconda.org/conda-forge/statista) [![Join the chat at https://gitter.im/Hapi-Nile/Hapi](https://badges.gitter.im/Hapi-Nile/Hapi.svg)](https://gitter.im/Hapi-Nile/Hapi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
 
-statista - Statistics package
-=====================================================================
-**statista** is a statistics package
+## Installation
 
-statista
+### Conda (Recommended)
 
-Main Features
--------------
-  - Statistical Distributions
-    - GEV
-    - GUMBEL
-    - Normal
-    - Exponential
-  - Parameter estimation methods
-    - Lmoments
-    - ML
-    - MOM
-  - One-at-time (O-A-T) Sensitivity analysis.
-  - Sobol visualization
-  - Statistical descriptors
-  - Extreme value analysis
+```bash
+conda install -c conda-forge statista
+```
 
-For the full documentation, please visit [statista documentation](https://statista.readthedocs.io/en/latest/?badge=latest)
+### PyPI
 
-Installing statista
-===============
+```bash
+pip install statista
+```
 
-Installing `statista` from the `conda-forge` channel can be achieved by:
+### Development Version
 
-```
-conda install -c conda-forge statista
+```bash
+pip install git+https://github.com/Serapieum-of-alex/statista
 ```
 
-It is possible to list all the versions of `statista` available on your platform with:
+## Main Features
 
-```
-conda search statista --channel conda-forge
-```
+### Statistical Distributions
+- **Probability Distributions**: GEV, Gumbel, Normal, Exponential, and more
+- **Parameter Estimation Methods**: Maximum Likelihood (ML), L-moments, Method of Moments (MOM)
+- **Goodness-of-fit Tests**: Kolmogorov-Smirnov, Chi-square
+- **Truncated Distributions**: Focus analysis on values above a threshold
 
-## Install from GitHub
-to install the last development to time, you can install the library from GitHub
-```
-pip install git+https://github.com/MAfarrag/statista
-```
+### Extreme Value Analysis
+- **Return Period Calculation**: Estimate extreme events for different return periods
+- **Confidence Intervals**: Calculate confidence bounds using various methods
+- **Plotting Positions**: Weibull, Gringorten, and other empirical distribution functions
+
+### Sensitivity Analysis
+- **One-at-a-time (OAT)**: Analyze parameter sensitivity individually
+- **Sobol Visualization**: Visualize parameter interactions and importance
+
+### Statistical Tools
+- **Descriptive Statistics**: Comprehensive statistical descriptors
+- **Time Series Analysis**: Auto-correlation and other time series tools
+- **Visualization**: Publication-quality plots for statistical analysis
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import pandas as pd
+from statista.distributions import Distributions
 
-## pip
-to install the last release, you can use pip
+# Load your time series data
+data = pd.read_csv("your_data.csv", header=None)[0].tolist()
+
+# Create a distribution object (e.g., Gumbel)
+dist = Distributions("Gumbel", data)
+
+# Fit the distribution using maximum likelihood
+params = dist.fit_model(method="mle")
+print(params)
+
+# Calculate and plot the PDF and CDF
+pdf = dist.pdf(plot_figure=True)
+cdf, _, _ = dist.cdf(plot_figure=True)
+
+# Perform goodness-of-fit tests
+ks_test = dist.ks()
+chi2_test = dist.chisquare()
+
+# Create a probability plot with confidence intervals
+fig, ax = dist.plot()
 ```
-pip install statista==0.6.0
+
+### Extreme Value Analysis
+
+```python
+from statista.distributions import GEV, PlottingPosition
+
+# Create a GEV distribution
+gev_dist = Distributions("GEV", data)
+
+# Fit using L-moments
+params = gev_dist.fit_model(method="lmoments")
+
+# Calculate non-exceedance probabilities
+cdf_weibul = PlottingPosition.weibul(data)
+
+# Calculate confidence intervals
+lower_bound, upper_bound, fig, ax = gev_dist.confidence_interval(plot_figure=True)
 ```
 
-Quick start
-===========
+For more examples and detailed documentation, visit [Statista Documentation](https://serapieum-of-alex.github.io/statista)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
+
+## Citation
+
+If you use Statista in your research, please cite it as:
 
 ```
-  >>> import statista
+Farrag, M. (2023). Statista: A Python package for statistical analysis, extreme value analysis, and sensitivity analysis. 
+https://github.com/Serapieum-of-alex/statista
 ```
 
-[other code samples](https://statista.readthedocs.io/en/latest/?badge=latest)
+BibTeX:
+```bibtex
+@software{statista2023,
+  author = {Farrag, Mostafa},
+  title = {Statista: A Python package for statistical analysis, extreme value analysis, and sensitivity analysis},
+  url = {https://github.com/Serapieum-of-alex/statista},
+  year = {2023}
+}
+```

AUTHORS.rst

@@ -0,0 +1,5 @@
+# Credits
+
+## Development Lead
+
+* Mostafa Farrag <moah.farag@gmail.com>