More structured documentation (no autodocs anymore)

9 warnings, considering this a Win.
NREL · Oct 4, 2019 · d7008ff · d7008ff
1 parent e08824f
commit d7008ff
Show file tree

Hide file tree

Showing 57 changed files with 628 additions and 59 deletions.
diff --git a/bifacial_radiance/main.py b/bifacial_radiance/main.py
@@ -185,7 +185,6 @@ class RadianceObj:
     nowstr : current date/time string
     path : working directory with Radiance materials and objects
 
-    
     Methods
     -------
     __init__ : initialize the object
@@ -737,7 +736,6 @@ def gendaylit(self, metdata, timeindex, debug=False):
         using Radiance internal sun position calculation (for that use gendaylit function)
         If material type is known, pass it in to get
         reflectance info.  if material type isn't known, material_info.list is returned
-        Note - -W and -O1 option is used to create full spectrum analysis in units of Wm-2
         
         Parameters
         ----------
@@ -800,6 +798,8 @@ def gendaylit(self, metdata, timeindex, debug=False):
             print('Warning: negative sun elevation at '+
                   '{}.  '.format(metdata.datetime[timeindex])+
                   'Re-calculated elevation: {:0.2}'.format(sunalt))
+
+        # Note - -W and -O1 option is used to create full spectrum analysis in units of Wm-2
          #" -L %s %s -g %s \n" %(dni/.0079, dhi/.0079, self.ground.ReflAvg) + \
         skyStr = ("# start of sky definition for daylighting studies\n" + \
             "# location name: " + str(locName) + " LAT: " + str(lat)
@@ -836,7 +836,6 @@ def gendaylit2manual(self, dni, dhi, sunalt, sunaz):
         """
         Sets and returns sky information using gendaylit.
         Uses user-provided data for sun position and irradiance.
-        Note: :option:`-W` and :option:`-O1` are used to create full spectrum analysis in units of Wm-2       
         
         .. warning::
             Currently half an hour offset is programed on timestamp, for wheater files.
@@ -860,6 +859,8 @@ def gendaylit2manual(self, dni, dhi, sunalt, sunaz):
 
         #TODO:
         # #DocumentationCheck
+        # Is the half hour warning thing still Valid
+        #
         # Documentation note: "if material type is known, pass it in to get
         # reflectance info.  if material type isn't known, material_info.list is returned"
         # I don't think this function is doing that still? Maybe just delete this lines?
@@ -872,6 +873,7 @@ def gendaylit2manual(self, dni, dhi, sunalt, sunaz):
             self.skyfiles = [None]
             return None
 
+        # Note: -W and -O1 are used to create full spectrum analysis in units of Wm-2       
          #" -L %s %s -g %s \n" %(dni/.0079, dhi/.0079, self.ground.ReflAvg) + \
         skyStr =   ("# start of sky definition for daylighting studies\n" + \
             "# Manual inputs of DNI, DHI, SunAlt and SunAZ into Gendaylit used \n" + \
@@ -3456,30 +3458,32 @@ def moduleAnalysis(self, scene, modWanted=None, rowWanted=None,
     def analysis(self, octfile, name, frontscan, backscan, plotflag=False, accuracy='low'):
         """
         General analysis function, where linepts are passed in for calling the
-        raytrace routine :py:class:`bifacial_radiance.analysis.irrPlotNew` 
-        and saved into results with :py:class:`~bifacial_radiance.AnalysisObj.saveResults`.
+        raytrace routine :py:class:`~bifacial_radiance.AnalysisObj.irrPlotNew` 
+        and saved into results with 
+        :py:class:`~bifacial_radiance.AnalysisObj.saveResults`.
         
-        This function can also plot: pass in the linepts structure of the view 
+        This function can also pass in the linepts structure of the view 
         along with a title string for the plots note that the plots appear in 
-        a blocking way unless you call pylab magic in the beginning.
+        a blocking way unless you call pylab magic in the beginning 
 
         Parameters
-        -----------
-        octfile : string
-            Filename and extension of .oct file
+        ------------
         name : string 
             Name to append to output files
+        octfile : string
+            Filename and extension of .oct file
         frontscan : scene.frontscan object
+            Object with the sensor location information for the front of the module
         backscan : scene.backscan object
+            Object with the sensor location information for the rear side of the module
         plotflag : boolean
             Include plot of resulting irradiance
         accuracy : string 
             Either 'low' (default - faster) or 'high' (better for low light)
-        
-        
+
         Returns
         -------
-        File saved in \results\irr_name.csv
+         File saved in `\results\irr_name.csv`
         
         """
         #

diff --git a/bifacial_radiance/readepw.py b/bifacial_radiance/readepw.py
@@ -1,12 +1,17 @@
 # -*- coding: utf-8 -*-
-
+"""
+Import functions for EPW data files.
+"""
 
 def readepw(filename=None):
     '''
     Reads an EPW file into a pandas dataframe.
     
-    Function tested with EnergyPlus weather data files: 
-    https://energyplus.net/weather
+    EPW files are commonly used by building simulation professionals
+    and are widely available on the web. For example via:
+    https://energyplus.net/weather , http://climate.onebuilding.org or
+    http://www.ladybug.tools/epwmap/
+
 
     Parameters
     ----------
@@ -25,11 +30,24 @@ def readepw(filename=None):
     metadata : dict
         The site metadata available in the file.
 
+
     Notes
-    -----
+    ------
 
     The returned structures have the following fields.
 
+    ===============   ======  ===================
+    key               format  description
+    ===============   ======  ===================
+    altitude          Float   site elevation
+    latitude          Float   site latitudeitude
+    longitude         Float   site longitudeitude
+    Name              String  site name
+    State             String  state
+    TZ                Float   UTC offset
+    USAF              Int     USAF identifier
+    ===============   ======  ===================
+
     =======================================================================
     Data field                       
     =======================================================================
@@ -64,23 +82,12 @@ def readepw(filename=None):
     Liquid precipitation depth in mm at indicated time
     Liquid precipitation quantity
     =======================================================================
-
-    ===============   ======  ===================
-    key               format  description
-    ===============   ======  ===================
-    altitude          Float   site elevation
-    latitude          Float   site latitudeitude
-    longitude         Float   site longitudeitude
-    Name              String  site name
-    State             String  state
-    TZ                Float   UTC offset
-    USAF              Int     USAF identifier
-    ===============   ======  ===================
     
     S. Quoilin, October 2017
     Downloaded from PVLib issue tracker on 3/16/18
     https://github.com/pvlib/pvlib-python/issues/261
     '''
+
     import pandas as pd
     def _interactive_load():
         import Tkinter

diff --git a/docs/sphinx/source/.index.rst.un~ b/docs/sphinx/source/.index.rst.un~
diff --git a/docs/sphinx/source/.installation.rst.un~ b/docs/sphinx/source/.installation.rst.un~
diff --git a/docs/sphinx/source/.manualapi.rst.swp b/docs/sphinx/source/.manualapi.rst.swp
diff --git a/docs/sphinx/source/.manualapi.rst.un~ b/docs/sphinx/source/.manualapi.rst.un~
diff --git a/docs/sphinx/source/.package_overview.rst.un~ b/docs/sphinx/source/.package_overview.rst.un~
diff --git a/docs/sphinx/source/.validation.rst.un~ b/docs/sphinx/source/.validation.rst.un~
diff --git a/docs/sphinx/source/.variables_style_rules.rst.un~ b/docs/sphinx/source/.variables_style_rules.rst.un~
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -58,35 +58,35 @@ def __getattr__(cls, name):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    #'sphinx.ext.autodoc',
-    #'sphinx.ext.mathjax',
-    #'sphinx.ext.viewcode',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'sphinx.ext.autodoc',
-    #'sphinx.ext.extlinks',
-    #'sphinx.ext.napoleon',
-    #'sphinx.ext.autosummary',
-    #'IPython.sphinxext.ipython_directive',
-    #'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',
+    'IPython.sphinxext.ipython_directive',
+    'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.doctest',
-    'autoapi.extension',
+    #'autoapi.extension',
     'sphinx.ext.todo'
 ]
 
 
 
 # Document Python Code
-autodoc_mock_imports = ['bs4', 'requests']
-autoapi_type = 'python'
-autoapi_dirs = '../../../bifacial_radiance'
+#autodoc_mock_imports = ['bs4', 'requests']
+#autoapi_type = 'python'
+#autoapi_dirs = '../../../bifacial_radiance'
 
-#napoleon_use_rtype = False  # group rtype on same line together with return
+napoleon_use_rtype = False  # group rtype on same line together with return
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-#source_suffix = '.rst'
+source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -114,9 +114,9 @@ def __getattr__(cls, name):
 exclude_patterns = ['whatsnew/*', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
-#pygments_style = 'sphinx'
+pygments_style = 'sphinx'
 
-#autosummary_generate = True
+autosummary_generate = True
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -146,8 +146,8 @@ def __getattr__(cls, name):
 htmlhelp_basename = 'bifacial_radiancedoc'
 
 # A workaround for the responsive tables always having annoying scrollbars.
-#def setup(app):
-#    app.add_stylesheet("no_scrollbars.css")
+def setup(app):
+    app.add_stylesheet("no_scrollbars.css")
 
 """    
 # -- Options for LaTeX output ---------------------------------------------

diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.analysis.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.analysis.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.analysis
+=======================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.analysis
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.irrPlotNew.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.irrPlotNew.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.irrPlotNew
+=========================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.irrPlotNew
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.makeFalseColor.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.makeFalseColor.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.makeFalseColor
+=============================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.makeFalseColor
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.makeImage.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.makeImage.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.makeImage
+========================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.makeImage
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.moduleAnalysis.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.moduleAnalysis.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.moduleAnalysis
+=============================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.moduleAnalysis
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.rst
@@ -0,0 +1,30 @@
+bifacial\_radiance.AnalysisObj
+==============================
+
+.. currentmodule:: bifacial_radiance
+
+.. autoclass:: AnalysisObj
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~AnalysisObj.__init__
+      ~AnalysisObj.analysis
+      ~AnalysisObj.irrPlotNew
+      ~AnalysisObj.linePtsMake3D
+      ~AnalysisObj.linePtsMakeDict
+      ~AnalysisObj.makeFalseColor
+      ~AnalysisObj.makeImage
+      ~AnalysisObj.moduleAnalysis
+      ~AnalysisObj.saveResults
+
+
+
+
+
+
diff --git a/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.saveResults.rst b/docs/sphinx/source/generated/bifacial_radiance.AnalysisObj.saveResults.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.AnalysisObj.saveResults
+==========================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: AnalysisObj.saveResults
diff --git a/docs/sphinx/source/generated/bifacial_radiance.GroundObj.rst b/docs/sphinx/source/generated/bifacial_radiance.GroundObj.rst
@@ -0,0 +1,22 @@
+bifacial\_radiance.GroundObj
+============================
+
+.. currentmodule:: bifacial_radiance
+
+.. autoclass:: GroundObj
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~GroundObj.__init__
+
+
+
+
+
+
diff --git a/docs/sphinx/source/generated/bifacial_radiance.MetObj.rst b/docs/sphinx/source/generated/bifacial_radiance.MetObj.rst
@@ -0,0 +1,23 @@
+bifacial\_radiance.MetObj
+=========================
+
+.. currentmodule:: bifacial_radiance
+
+.. autoclass:: MetObj
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~MetObj.__init__
+      ~MetObj.set1axis
+
+
+
+
+
+
diff --git a/docs/sphinx/source/generated/bifacial_radiance.MetObj.set1axis.rst b/docs/sphinx/source/generated/bifacial_radiance.MetObj.set1axis.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.MetObj.set1axis
+==================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: MetObj.set1axis
diff --git a/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.genCumSky.rst b/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.genCumSky.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.RadianceObj.genCumSky
+========================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: RadianceObj.genCumSky
diff --git a/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.genCumSky1axis.rst b/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.genCumSky1axis.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.RadianceObj.genCumSky1axis
+=============================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: RadianceObj.genCumSky1axis
diff --git a/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.gendaylit.rst b/docs/sphinx/source/generated/bifacial_radiance.RadianceObj.gendaylit.rst
@@ -0,0 +1,6 @@
+bifacial\_radiance.RadianceObj.gendaylit
+========================================
+
+.. currentmodule:: bifacial_radiance
+
+.. automethod:: RadianceObj.gendaylit