From bbb88f12aa6944d1c19bf43673790137cc386744 Mon Sep 17 00:00:00 2001
From: Adiv Paradise <paradise@astro.utoronto.ca>
Date: Tue, 8 Dec 2020 14:54:50 -0500
Subject: [PATCH] Documents the stellar spectrum generator; added mock imports
 to conf.py

---
 docs/conf.py                 | 15 +++++++---
 docs/source/exoplasim.rst    |  9 ++++++
 exoplasim/makestellarspec.py | 54 ++++++++++++++++++++++++++++++++----
 3 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 99b1491..fe0a969 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,10 +14,17 @@ import os
 import sys
 sys.path.insert(0, os.path.abspath('../exoplasim'))
 
-#import mock, sys
-#MOCK_MODULES = ['exoplasim','exoplasim.gcmt','netCDF4','numpy']
-#for mod_name in MOCK_MODULES:
-    #sys.modules[mod_name] = mock.Mock()
+from mock import Mock as MagicMock
+ 
+class Mock(MagicMock):
+    @classmethod
+    def __getattr__(cls, name):
+        return MagicMock()
+ 
+MOCK_MODULES = ['numpy', 'scipy', 'matplotlib.colors','matplotlib.pyplot','exoplasim',
+                'exoplasim.gcmt','exoplasim.randomcontinents','exoplasim.makestellarspec']
+sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
+
 # -- Project information -----------------------------------------------------
 
 project = 'ExoPlaSim'
diff --git a/docs/source/exoplasim.rst b/docs/source/exoplasim.rst
index 7507878..865c6f5 100644
--- a/docs/source/exoplasim.rst
+++ b/docs/source/exoplasim.rst
@@ -21,6 +21,15 @@ exoplasim.randomcontinents module
    :undoc-members:
    :show-inheritance:
 
+
+exoplasim.makestellarspec module
+--------------------------------
+
+.. automodule:: exoplasim.makestellarspec
+   :members:
+   :undoc-members:
+   :show-inheritance:   
+   
 Module contents
 ---------------
 
diff --git a/exoplasim/makestellarspec.py b/exoplasim/makestellarspec.py
index 73923b1..fc5db40 100644
--- a/exoplasim/makestellarspec.py
+++ b/exoplasim/makestellarspec.py
@@ -3,6 +3,10 @@ import matplotlib.pyplot as plt
 import sys
 
 """
+========================
+Stellar Spectrum Utility
+========================
+
 Convert spectral files to exoplasim-compliant formats, including resampling
 to the necessary resolutions.
 
@@ -11,12 +15,36 @@ Usage
 
 python makestellarspec.py spectrum.txt mystarsname
 
+Yields
+------
+mystarsname.dat
+    965 wavelengths
+mystarsname_hr.dat
+    2048 wavelengths
+
 """
 
 
 cc = 299792458.0 #Speed of light
 
 def readspec(sfile,cgs=False):
+    """Read a Phoenix stellar spectrum and return wavelengths, fluxes, and units
+    
+    Takes as input a spectrum file generated by the Phoenix stellar spectrum web simulator,
+    https://phoenix.ens-lyon.fr/simulator-jsf22-26.
+    
+    Parameters
+    ----------
+    sfile : str
+        Path to the spectrum file
+    cgs : bool, optional
+        Whether or not we should try to use CGS units (irrelevant for exoplasim)
+        
+    Returns
+    -------
+    numpy.ndarray, numpy.ndarray, str
+        Returns wavelengths, fluxes, and the units
+    """
     f=open(sfile,"r")
     ftxt = f.read()
     if ftxt[0]=='#':
@@ -67,7 +95,7 @@ def readspec(sfile,cgs=False):
         fluxes[:] = fluxes[:]*10.0 #W/m^2/micron
     return wvls,fluxes,units
 
-def coarsen(wvls,fluxes,w1,w2,num=5000):
+def _coarsen(wvls,fluxes,w1,w2,num=5000):
     inds = np.arange(len(wvls))
     nlow = (inds[wvls>w1])[0]
     nhigh= (inds[wvls>w2])[0]
@@ -90,18 +118,34 @@ def coarsen(wvls,fluxes,w1,w2,num=5000):
         
     return waves,flxs2
 
-def integrate_trap(x,y):
+def _integrate_trap(x,y):
     net = 0
     for n in range(1,len(y)):
         net += 0.5*(x[n]-x[n-1])*(y[n]+y[n-1])
     return net
 
-def normalize(wvls,fluxes):
+def _normalize(wvls,fluxes):
     netf = np.trapz(fluxes,x=wvls)
     factor = 1366.941858/netf
     return fluxes*factor
 
 def writedat(wvls,fluxes,name):
+    """Write wavelengths and fluxes to a .dat file ExoPlaSim can read.
+    
+    Parameters
+    ----------
+    wvls : array-like
+        An array-like object containing a monotonic list of wavelengths going from short to long
+    fluxes : array-like
+        An array-like object containing a flux for each wavelength in ``wvls``.
+    name : str
+        A name to use when generating output files.
+        
+    Yields
+    ------
+    name.dat
+        The provided spectrum in a format ExoPlaSim can read.
+    """
     f=open(name+".dat","w")
     sdat = ' Wavelength    Flux  \n'
     for n in range(0,len(wvls)):
@@ -128,7 +172,7 @@ if __name__=="__main__":
     plt.xscale('log')
     plt.yscale('log')
     plt.show()
-    #wc,fc = coarsen(w,f,wave0,wave1,num=numw*4)
+    #wc,fc = _coarsen(w,f,wave0,wave1,num=numw*4)
     #plt.plot(wc,fc)
     #plt.xscale('log')
     #plt.yscale('log')
@@ -147,7 +191,7 @@ if __name__=="__main__":
         factor = 1366.941858/E1
         f2*=factor
         print(np.trapz(f2,x=w2))
-        print(np.trapz(normalize(w,f),x=w))
+        print(np.trapz(_normalize(w,f),x=w))
     #print f2[np.argwhere(w2>40.0)],w[-10:]
     plt.plot(w2,f2)
     #plt.plot(wc,fc)