docs: Add documentation pages with mkdocs

fix(ci.yml): mod ci.yml

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci 
+on:
+  push:
+    branches:
+      - master 
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocstrings[python] mkdocs-material pymdown-extensions
+      - run: pip install .
+      - run: mkdocs gh-deploy --force

README.md

@@ -1,23 +1,81 @@
 # shimeri
 
-## Overview
-
 A Python package for calculating psychrometric properties of moist air and plotting psychrometric charts based on plotly.
 
-## Motivation
-Psychrometric charts are drawn on an oblique coordinate system with enthalpy and humidity ratio as axes.  
-As a result, dry-bulb temperatures are not precisely equidistant.  
-This tool managed this characteristic.
-
+*shimeri* means "moisture" or "humidity" in Japanese.
 
 ## Installation
 
-```bash
+``` sh
 pip install shimeri
 ```
 
-## Usage
-[See sample.py](/sample.py)
+## Quick Usage
+
+Usage example below.
+
+``` py title="sample.py"
+import shimeri as sh
+import numpy as np
+
+if __name__ == "__main__":
+    # instantiate psychrometric calculator
+    pc = sh.PsychrometricCalculator()
+
+    # calculate psychrometric properties at 25degC dry-bulb temperature and 50% relative humidity
+    db, wb, rh, hr, en = pc.get_all(db=25, rh=50)
+    print(
+        f"DB={db:.1f}degC, WB={wb:.1f}degC, RH={rh:.1f}%, HR={hr:.1f}g/kg, EN={en:.1f}kJ/kg"
+    )
+
+    # initialize a psychrometric chart
+    fig = sh.PsychrometricChart()
+
+    # plot random points
+    rng = np.random.default_rng()
+    dbs = rng.normal(25, 5, 30)
+    rhs = rng.normal(50, 5, 30)
+    dbs, wbs, rhs, hrs, ens = pc.get_all(db=dbs, rh=rhs)
+    fig.add_points(
+        en=ens,
+        hr=hrs,
+        name="random points",
+        mode="markers",
+    )
+
+    # add a line from points
+    dbs = np.array([26.0, 35.0])
+    rhs = np.array([50.0, 60.0])
+    hrs = pc.get_hr_from_db_rh(dbs, rhs)
+    ens = pc.get_en_from_db_hr(dbs, hrs)
+    fig.add_points(
+        en=ens,
+        hr=hrs,
+        name="line",
+        mode="lines",
+    )
+
+    # draw constant humidity ratio line from half-mixed point to rh=90%
+    hr_mixed = (hrs[0] + hrs[1]) * 0.5
+    db_mixed = (dbs[0] + dbs[1]) * 0.5
+
+    db_90, wb_90, rh_90, hr_90, en_90 = pc.get_all(hr=hr_mixed, rh=90)
+
+    fig.draw_iso_hr_line(
+        hr=hr_mixed,
+        db_range=np.array([db_mixed, db_90]),
+        mode="lines+markers",
+    )
+
+    # draw a line of constant relative humidity
+    fig.draw_iso_rh_line(
+        rh=90,
+        db_range=np.array([db_90, 15.0]),
+        mode="lines",
+    )
+
+    fig.show()
+```
 
 Sample Result:  
 ![Sample Result](https://github.com/yutaka-shoji/shimeri/blob/main/sample.png?raw=true)

docs/api/psychrometricchart.md

@@ -0,0 +1 @@
+::: shimeri.psychrometricchart

docs/api/psychrometrics.md

@@ -0,0 +1,6 @@
+::: shimeri.psychrometrics
+    options:
+        # explicit members list
+        members:
+          - PsychrometricCalculator
+          - get_saturation_pressure

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

docs/license.md

@@ -0,0 +1 @@
+--8<-- "LICENSE"

mkdocs.yml

@@ -0,0 +1,43 @@
+site_name: "shimeri"
+site_url: "https://yutaka-shoji.shimeri.github.io/"
+
+theme:
+  name: "material"
+  features:
+    - content.code.copy
+
+repo_name: yutaka-shoji/shimeri
+repo_url: https://github.com/yutaka-shoji/shimeri
+copyright: Copyright © 2024 Shoji, Yutaka
+
+nav:
+- Home:
+  - Overview: index.md
+  - License: license.md
+- API reference:
+    psychrometrics: api/psychrometrics.md
+    psychrometricchart: api/psychrometricchart.md
+
+plugins:
+- search
+- mkdocstrings:
+    handlers:
+      python:
+        paths: [.]
+        options:
+          members_order: alphabetical
+
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

pyproject.toml

@@ -25,6 +25,9 @@ managed = true
 dev-dependencies = [
     "ruff>=0.5.2",
     "pyright>=1.1.371",
+    "mkdocstrings[python]>=0.25.1",
+    "mkdocs-material>=9.5.29",
+    "pymdown-extensions>=10.8.1",
 ]
 
 [tool.hatch.metadata]

requirements-dev.lock

@@ -9,18 +9,103 @@
 #   generate-hashes: false
 
 -e file:.
+babel==2.15.0
+    # via mkdocs-material
+backports-strenum==1.3.1
+    # via griffe
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via mkdocs
+    # via mkdocstrings
+colorama==0.4.6
+    # via griffe
+    # via mkdocs-material
+ghp-import==2.1.0
+    # via mkdocs
+griffe==0.48.0
+    # via mkdocstrings-python
+idna==3.7
+    # via requests
+jinja2==3.1.4
+    # via mkdocs
+    # via mkdocs-material
+    # via mkdocstrings
+markdown==3.6
+    # via mkdocs
+    # via mkdocs-autorefs
+    # via mkdocs-material
+    # via mkdocstrings
+    # via pymdown-extensions
+markupsafe==2.1.5
+    # via jinja2
+    # via mkdocs
+    # via mkdocs-autorefs
+    # via mkdocstrings
+mergedeep==1.3.4
+    # via mkdocs
+    # via mkdocs-get-deps
+mkdocs==1.6.0
+    # via mkdocs-autorefs
+    # via mkdocs-material
+    # via mkdocstrings
+mkdocs-autorefs==1.0.1
+    # via mkdocstrings
+mkdocs-get-deps==0.2.0
+    # via mkdocs
+mkdocs-material==9.5.29
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocstrings==0.25.1
+    # via mkdocstrings-python
+mkdocstrings-python==1.10.5
+    # via mkdocstrings
 nodeenv==1.9.1
     # via pyright
 numpy==2.0.0
     # via scipy
     # via shimeri
 packaging==24.1
+    # via mkdocs
     # via plotly
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via mkdocs
+platformdirs==4.2.2
+    # via mkdocs-get-deps
+    # via mkdocstrings
 plotly==5.22.0
     # via shimeri
+pygments==2.18.0
+    # via mkdocs-material
+pymdown-extensions==10.8.1
+    # via mkdocs-material
+    # via mkdocstrings
 pyright==1.1.371
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.1
+    # via mkdocs
+    # via mkdocs-get-deps
+    # via pymdown-extensions
+    # via pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+regex==2024.5.15
+    # via mkdocs-material
+requests==2.32.3
+    # via mkdocs-material
 ruff==0.5.2
 scipy==1.13.1
     # via shimeri
+six==1.16.0
+    # via python-dateutil
 tenacity==8.5.0
     # via plotly
+urllib3==2.2.2
+    # via requests
+watchdog==4.0.1
+    # via mkdocs

src/shimeri/psychrometricchart.py

@@ -16,7 +16,7 @@ def __init__(self, pressure: float = 101.325):
         Initialize the PsychrometricChart class.
 
         Args:
-            pressure: Atmospheric pressure in kPa. Default is 101.325 kPa.
+            pressure: Atmospheric pressure in kPa.
         """
         super().__init__()
 
@@ -125,7 +125,6 @@ def draw_iso_rh_line(
         Args:
             rh: Relative humidity (%) as a float.
             db_range: Range of dry bulb temperatures (degC) for which to draw the line.
-                      Default is [-10, 70].
             **kwargs: Additional keyword arguments to be passed to plotly's go.Scatter.
         """
         dbs = np.linspace(db_range[0], db_range[-1], 100)
@@ -148,7 +147,6 @@ def draw_iso_db_line(
         Args:
             db: Dry bulb temperature (degC) as a float.
             rh_range: Range of relative humidities (%) for which to draw the line.
-                       Default is [0, 100].
             **kwargs: Additional keyword arguments to be passed to plotly's go.Scatter.
         """
         rhs = np.linspace(rh_range[0], rh_range[-1], 100)
@@ -171,7 +169,6 @@ def draw_iso_hr_line(
         Args:
             hr: Humidity ratio (g/kg) as a float.
             db_range: Range of dry bulb temperatures (degC) for which to draw the line.
-            Default is [-10, 70].
             **kwargs: Additional keyword arguments to be passed to plotly's go.Scatter.
         """
         dbs = np.array(db_range)
@@ -194,7 +191,6 @@ def draw_iso_en_line(
         Args:
             en: Specific enthalpy (kJ/kg) as a float.
             db_range: Range of dry bulb temperatures (degC) for which to draw the line.
-                      Default is [-10, 70].
             **kwargs: Additional keyword arguments to be passed to plotly's go.Scatter.
         """
         dbs = np.array(db_range)