Add docs to the project

- Provide sphinx documentation for the pysolorie project. For now it just contains the module's docs.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,21 @@
+project = "pysolorie"
+copyright = "2023, Alireza Aghamohammadi"
+author = "Alireza Aghamohammadi"
+
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
+    "sphinx.ext.viewcode",
+]
+
+
+pygments_style = "sphinx"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+autoclass_content = "both"
+
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,22 @@
+.. pysolorie documentation master file, created by
+   sphinx-quickstart on Sun Dec 10 14:02:09 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to pysolorie's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   reference/modules
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/reference/modules.rst

@@ -0,0 +1,7 @@
+pysolorie
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   pysolorie

docs/reference/pysolorie.atmospheric_transmission.rst

@@ -0,0 +1,7 @@
+pysolorie.atmospheric\_transmission module
+==========================================
+
+.. automodule:: pysolorie.atmospheric_transmission
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/pysolorie.irradiance.rst

@@ -0,0 +1,7 @@
+pysolorie.irradiance module
+===========================
+
+.. automodule:: pysolorie.irradiance
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/pysolorie.model.rst

@@ -0,0 +1,7 @@
+pysolorie.model module
+======================
+
+.. automodule:: pysolorie.model
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/pysolorie.numerical_integration.rst

@@ -0,0 +1,7 @@
+pysolorie.numerical\_integration module
+=======================================
+
+.. automodule:: pysolorie.numerical_integration
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/pysolorie.observer.rst

@@ -0,0 +1,7 @@
+pysolorie.observer module
+=========================
+
+.. automodule:: pysolorie.observer
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/pysolorie.rst

@@ -0,0 +1,20 @@
+pysolorie package
+=================
+
+.. automodule:: pysolorie
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pysolorie.atmospheric_transmission
+   pysolorie.irradiance
+   pysolorie.model
+   pysolorie.numerical_integration
+   pysolorie.observer
+   pysolorie.sun_position

docs/reference/pysolorie.sun_position.rst

@@ -0,0 +1,7 @@
+pysolorie.sun\_position module
+==============================
+
+.. automodule:: pysolorie.sun_position
+   :members:
+   :undoc-members:
+   :show-inheritance:

setup.cfg

@@ -88,3 +88,17 @@ deps =
     flake8-bugbear
 commands =
     flake8 {posargs:src tests}
+
+[testenv:docs]
+deps =
+    sphinx
+    sphinx-rtd-theme
+commands =
+    sphinx-apidoc \
+        --force \
+        --implicit-namespaces \
+        --module-first \
+        --separate \
+        -o docs/reference/ \
+        src/pysolorie/
+    sphinx-build -W -b html docs/ docs/_build/

src/pysolorie/atmospheric_transmission.py

@@ -18,19 +18,16 @@
 
 
 class AtmosphericTransmission:
-    """
-    This class calculates the effective atmospheric transmission coefficient
-    of the direct beam.
-    """
-
     def __init__(
         self,
         climate_type: str,
         observer_altitude: int,
         observer_latitude: float,
     ):
         r"""
-        Initialize the AtmosphericTransmission class.
+        To instantiate the ``AtmosphericTransmission`` class,
+        provide the following three parameters.
+
 
         :param climate_type: The type of climate.
         :type climate_type: str
@@ -57,13 +54,14 @@ def calculate_transmittance(self, day_of_year: int, solar_time: float) -> float:
         is calculated using the formula:
 
         .. math::
-            \tau_b = a_0 + a_1 \cdot \exp\left(-\frac{k}{\cos(\theta_z)}\right)
+            \tau_b = a_0 + a_1 \times \exp\left(-\frac{k}{\cos(\theta_z)}\right)
 
-        where:
-        \(\tau_b\) is the effective atmospheric transmission coefficient
-        of the direct beam, \(a_0\), \(a_1\), and \(k\)
-        are the components of clear-sky beam radiation transmittance,
-        and \(\theta_z\) is the zenith angle.
+
+        | - :math:`\tau_b` is the effective atmospheric transmission
+            coefficient of the direct beam
+        | - :math:`a_0`, :math:`a_1`, and :math:`k` are the components
+            of clear-sky beam radiation transmittance
+        | - :math:`\theta_z` is the zenith angle
 
         :param day_of_year: The day of the year.
         :type day_of_year: int
@@ -72,6 +70,7 @@ def calculate_transmittance(self, day_of_year: int, solar_time: float) -> float:
         :return: The effective atmospheric transmission coefficient of the direct beam.
         :rtype: float
         """
+
         zenith_angle = self.observer.calculate_zenith_angle(day_of_year, solar_time)
         cos_zenith_angle = math.cos(zenith_angle)
         EPSILON = 1e-8  # Small constant to prevent division by zero

src/pysolorie/irradiance.py

@@ -20,10 +20,11 @@
 class SolarIrradiance:
     def __init__(self, sun_position: SunPosition):
         r"""
-        Initialize the SolarIrradiance class.
+        To instantiate the ``SolarIrradiance`` class, provide the following parameter.
+
 
         :param sun_position: An instance of the SunPosition class.
-        :type sun_position: SunPosition
+        :type sun_position: pysolorie.SunPosition
         """
         self.sun_position = sun_position
 
@@ -38,17 +39,18 @@ def calculate_extraterrestrial_irradiance(self, day_of_year: int) -> float:
         The formula used is:
 
         .. math::
-
-            E = \text{{SOLAR\_CONSTANT}}
-            \times (1 + 0.33 \times \cos (2
-            \times \pi \times \frac{{\text{{day\_of\_year}}}}{365}))
-
-        where:
-        \(\text{{SOLAR\_CONSTANT}}\) is the average solar radiation arriving outside
-        of the Earth's atmosphere, which is approximately 1367 Watts per square meter.
-        This is also known as the solar constant.The factor 0.033 accounts
-        for the variation in the Earth-Sun distance
-        due to the Earth's elliptical orbit.
+            E = SC
+            \times (1 + 0.33 \times \cos (\frac{2\pi~n}{365}))
+
+
+        | - :math:`SC` is the average solar radiation arriving outside
+           of the Earth's atmosphere,
+           which is approximately ``1367`` Watts per square meter.
+           This is also known as the solar constant.
+        | - The factor ``0.033`` accounts
+          for the variation in the Earth-Sun distance
+          due to the Earth's elliptical orbit.
+        | - :math:`n` is the day of the year (i.e., ``day_of_year``)
 
         :param day\_of\_year: The day of the year, ranging from 1 to 365.
         :type day\_of\_year: int

src/pysolorie/model.py

@@ -20,8 +20,8 @@ class HottelModel:
     Hottel Model for estimating clear-sky beam radiation transmittance
     based on climate type, and observer altitude.
 
-    :ivar CLIMATE_CONSTANTS: Correction factors for different climate types
-    (\(r_0\), \(r_1\), and \(r_k\)).
+    ``CLIMATE_CONSTANTS``: Correction factors for different climate types
+    :math:`r_0`, :math:`r_1`, and :math:`r_k`.
     """
 
     CLIMATE_CONSTANTS: Dict[str, Tuple[float, float, float]] = {
@@ -101,23 +101,29 @@ def calculate_transmittance_components(
     ) -> Tuple[float, float, float]:
         r"""
         Calculate the components of clear-sky beam radiation transmittance
-        (\(a_0\), \(a_1\), and \(k\)) based on climate type and observer altitude.
+        :math:`a_0`, :math:`a_1`, and :math:`k`
+        based on climate type and observer altitude.
 
-        Correction factors adjust the clear-sky beam radiation transmittance components.
 
-        The formulas used to calculate the components are:
+        Correction factors adjust the clear-sky beam
+        radiation transmittance components. According
+        to the following formulas:
 
         .. math::
-            a_0 = r_0 \cdot a_0^*
-            a_1 = r_1 \cdot a_1^*
-            k = r_k \cdot k^*
+            a_0 = r_0 \times a_0^*
 
-        :param climate_type: Climate type (e.g., "TROPICAL").
+            a_1 = r_1 \times a_1^*
+
+            k = r_k \times k^*
+
+        :param climate_type: Climate type
+               (i.e., ``TROPICAL``, ``MIDLATITUDE SUMMER``,
+               ``SUBARCTIC SUMMER``, or ``MIDLATITUDE WINTER``).
         :type climate_type: str
         :param observer_altitude: Altitude of the observer in meters.
         :type observer_altitude: float
         :return: Components of clear-sky beam radiation transmittance
-        (\(a_0\), \(a_1\), \(k\)).
+                (:math:`a_0`, :math:`a_1`, :math:`k`).
         :rtype: tuple of floats
         :raises ValueError: If an invalid climate type is provided.
         """