Merge pull request #14 from aaghamohammadi/dev

Ready to release v1.5.2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,10 +1,5 @@
 ---
 name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
-
 ---
 
 **Describe the bug**
@@ -25,13 +20,6 @@ If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
  - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
-
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
  - Version [e.g. 22]
 
 **Additional context**

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,10 +1,5 @@
 ---
 name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**

.gitignore

@@ -174,3 +174,8 @@ poetry.toml
 pyrightconfig.json
 
 # End of https://www.toptal.com/developers/gitignore/api/python
+
+# joss
+paper/media/
+*.jats
+*.pdf

README.md

@@ -25,17 +25,63 @@ How can one maximize the solar irradiation energy received by a solar panel?
 
 ``pysolorie`` is a library designed to help you find this optimal orientation. Its features include, but are not limited to:
 
-- Finding the optimal orientation for a fixed solar panel, assuming a clear-sky model.
-- Plotting the optimal orientation over a range of days.
+- Finding the optimal tilt angle for a fixed solar panel, assuming a clear-sky condition.
+- Plotting the optimal tilt angle over a range of days.
 - Plotting the total direct irradiation over a range of days.
-- Generating a CSV report detailing the optimal orientation over a range of days.
+- Generating a CSV, JSON, or XML report detailing the optimal tilt angle over a range of days.
 - Calculating the sunrise and sunset hour angles for a specific day.
-- Utilizing Hottel’s Model to estimate the transmittance of clear-sky beam radiation.
+- Utilizing Hottel's model to quantify clear-sky conditions and estimate the atmospheric transmission of clear-sky beam radiation.
 - Calculating the solar zenith angle.
 - Calculating the solar time.
 - Calculating solar declination and hour angle.
 
+# How to Install pysolorie
 
+``pysolorie`` requires Python 3.9 or higher.
+
+The easiest way to install ``pysolorie`` is from PyPI.
+
+```bash
+python3 -m pip install pysolorie
+```
+
+
+## Example Usage
+With the pysolorie package, you can plot the optimal orientation of a solar panel given the climate type, altitude, and latitude of the location. For instance, the following code plots the optimal orientation for each day of the year for the city of Tehran. For more examples, please refer to the [Getting started](https://pysolorie.readthedocs.io/en/latest/getting_started.html) section of our documentation. The full [API Reference](https://pysolorie.readthedocs.io/en/latest/reference/modules.html) is also available on our website.
+
+```python
+from pathlib import Path
+from pysolorie import IrradiationCalculator, Plotter
+
+# Instantiate a Plotter object from the pysolorie library
+plotter = Plotter()
+
+# Instantiate an IrradiationCalculator object for the city of Tehran
+irradiation_calculator = IrradiationCalculator(
+    climate_type="MIDLATITUDE SUMMER",
+    observer_altitude=1200,
+    observer_latitude=35.6892
+)
+
+
+# Use the plotter to plot the optimal orientation of a solar panel for each day of the year
+plotter.plot_optimal_orientation(
+    irradiation_calculator,
+    from_day=1,
+    to_day=365,
+    path=Path("results.svg"),
+    plot_kwargs={
+        "xlabel": "Day",
+        "ylabel": "Beta (degrees)",
+        "title": "Optimal Solar Panel Orientation",
+    },
+    savefig_kwargs={"dpi": 300},
+)
+```
+
+This figure, generated by the example code, illustrates the optimal orientation of a solar panel for each day of the year in Tehran. The x-axis represents the day of the year, while the y-axis represents the optimal angle (Beta) in degrees. As can be seen, the optimal angle varies throughout the year, highlighting the importance of adjusting the orientation of the solar panel to maximize the energy received.
+
+<img src="docs/_static/images/example_usage.svg" width="600">
 
 ## Documentation
 

docs-requirements.txt

@@ -1,2 +1,3 @@
 sphinx
+sphinx-copybutton
 sphinx-rtd-theme