From 7147ea90f007992d13fe4890269149cfe2ac17cd Mon Sep 17 00:00:00 2001 From: Tom Keffer Date: Thu, 10 Jan 2019 06:42:19 -0800 Subject: [PATCH] Finished section "How options work" --- docs/customizing.htm | 147 +++++++++++++++++++++++++++---------------- 1 file changed, 93 insertions(+), 54 deletions(-) diff --git a/docs/customizing.htm b/docs/customizing.htm index f089fda1..b93c00ff 100644 --- a/docs/customizing.htm +++ b/docs/customizing.htm @@ -667,7 +667,7 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\

Customizing reports

- There are two general mechanisms for customizing reports: + There are two general mechanisms for customizing reports: change options in one or more configuration files, or change the template files. The former is generally easier, but occasionally the latter is necessary. @@ -691,7 +691,7 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\ Options are used in WeeWX to specify how your reports will look and what they will contain. For example, they control what units to use, how to format a string, what color to use for a plot line, etc. They all work the same way and obey a hierarchy, allowing skin writers to specify a look and feel of a - report, while ensuring that you still have the final say in how it will come out. + report, while ensuring that you still have the final say of how it will come out.

@@ -712,7 +712,7 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\ [StdReport] / [[report_name]] Affects only the report report_name. - Has the final say. + Highest precedence. Has the final say. weewx.conf @@ -737,9 +737,11 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\ +

Changing labels

Let's look at an example. If you take a look inside the file weewx/defaults.py, - you'll see it contains what looks like a big configuration file. Among other things, it has an entry + you'll see it contains what looks like a big configuration file. Among other things, it has two entries + that look like this: 

 ...
@@ -747,17 +749,19 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\
 ...
     [[Generic]]
         ...
+        inTemp = Inside Temperature
         outTemp = Outside Temperature

- This tells the report generators that when it is time to label the observation variable outTemp, - use the string Outside Temperature. Because weewx/defaults.py - sits at the bottom of the options hierarchy, this string will be used only when nothing else is available. + This tells the report generators that when it comes time to label the observation variables inTemp + and outTemp, use the strings InsideTemperature and Outside Temperature, respectively. Because weewx/defaults.py + sits at the bottom of the options hierarchy, these strings will be used only when nothing else is available.

Now suppose we have a skin called Life . Its configuration file will be - located at skins/Life/skin.conf. Among other things, it contains an excerpt + located at skins/Life/skin.conf. Suppose, among other things, it contains an excerpt 

@@ -772,7 +776,8 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\
         

             What this says is that the writer of Life, for whatever reasons, decided
             that s/he wants to use the string Exterior Temperature, instead of
-            Outside Temperature.
+            Outside Temperature for the label for outTemp.
+            There is no override for inTemp.
         

         

           Finally, for purposes of illustrating the hierarchy, suppose the [StdReport]
@@ -782,49 +787,109 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\
         
 [StdReport]
     ...
-    [[Defaults]]
-        [[[Labels]]]
-            [[[[Generic]]]]
-                outTemp = Shed Temperature
+
     [[LifeA]]
+        skin = Seasons
+
+    [[LifeB]]
         skin = Life
         [[[Labels]]]
             [[[[Generic]]]]
                 outTemp = Barn Temperature
-    [[LifeB]]
-        skin = Seasons
 

 
-        
Need an example that shows the behavior of weewx/defaults.py

         

-            then this will result in reports with the following values:
+            This will result in reports with the following values:
         

 
         
+                
-                
+                
+                
+                
+                
+            
+        

             

                 ReportLabel for inTemp
                 Label for outTemp
             

             

                 LifeABarn TemperatureInside TemperatureExterior Temperature
             

             

                 LifeBInside TemperatureBarn Temperature

+
+        

+            Note how the values specified for inTemp are not overridden anywhere, so the value
+            specified in weewx/defaults.py, that is, Inside Temperature, is used. By contrast, a value for outTemp
+            was specified in the skin so, in the absence of any user override, its value, ExteriorTemperature
+            will be used as the new default. Finally, for the report LifeB, the user
+            has specified an override for outTemp, so that value, Barn Temperature,
+            is used.
+        

+
+        

+            One more example. This time, suppose the [StdReport]
+            section of weewx.conf contains this:
+        

+
+        
+[StdReport]
+    ...
+
+    [[Defaults]]
+        [[[Labels]]]
+            [[[[Generic]]]]
+                outTemp = Shed Temperature
+
+
+    [[LifeA]]
+        skin = Seasons
+
+    [[LifeB]]
+        skin = Life
+        [[[Labels]]]
+            [[[[Generic]]]]
+                outTemp = Barn Temperature
+

+        

+            We have added a new section (highlighted), where the user has specified
+            a new default for the observation type outTemp, that is, Shed Temperature.
+            Unless overridden, this is the value that will now be used instead of what the skin writer specified.
+            The final tally looks like this:
+        

+
+        
+            
+                
+                
+                
+            
+            
+                
+                
+            
+                
+                
+                
+            
ReportLabel for inTempLabel for outTemp
LifeAInside Temperature
                 Shed Temperature
             
LifeBInside TemperatureBarn Temperature

         

 
         
How to change units

 
         

-            This section illustrates the use of options by selectively changing the units in reports.
+            Some users prefer to see metric units, others prefer US customary units. And there are other cases where
+            metric/US is not enough; some sites need metric units for most measurements, but wind speeds in knots, or some sites need rainfall in mm whereas others need
+            cm.
         

         

-            Some users prefer to see metric units, others prefer US customary units.  And there are other cases where metric/US is not enough; some sites need metric units for most measurements, but wind speeds in knots, or some sites need rainfall in mm whereas others need cm.
-        

-        

-            The examples that follow refer to the skin Seasons, which comes with the distribution.
+            This section shows how to specify exactly what units you want to use for which reports.
+            The examples use the skin Seasons, which comes with the distribution.
         

 
         

@@ -910,7 +975,9 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\
                 group_temperature  = degree_C             # Options are 'degree_F' or 'degree_C'

- The options that were changed have been  highlighted . + The options that were changed have been  highlighted . Note that + the changes occurred under the subsection [[Defaults]], so they + will affect all reports.

@@ -996,34 +1063,6 @@ db_manager.getSql("SELECT SUM(rain) FROM %s "\

-

How to change observation labels

- -

- Here's another example. Suppose your weather console is actually located in a barn, not indoors, and you - want any labels for the temperature measured by the console to be labeled "Barn Temperature," - rather than the default "Inside Temperature." This can be done by changing the inTemp, - located in section [Labels][[Generic]], from - the default -

- 
[Defaults]
-    [[Labels]]
-        [[[Generic]]]
-            inTemp  = Inside Temperature
-            outTemp = Outside Temperature
-

to:

- 
[Defaults]
-    [[Labels]]
-        [[[Generic]]]
-            inTemp  = Barn Temperature
-            outTemp = Outside Temperature
- -

- With this change, all observations of console temperature (database column inTemp), such as in an HTML report, or a plot, will now be - labeled "Barn Temperature." Because this is under the [Defaults] section, this change will apply to all reports. -

- -

Scheduling report generation

@@ -5964,7 +6003,7 @@ cooling_base = 20.0, degree_C charts, this is the color of the outline of the bar. Default is 0xff0000, 0x00ff00, 0x0000ff.

- Individual line color can be overridden by using option color. + Individual line color can be overridden by using option color.

chart_fill_colors

@@ -5982,7 +6021,7 @@ cooling_base = 20.0, degree_C Optional. Default is 1, 1, 1.

- Individual line widths can be overridden by using option width. + Individual line widths can be overridden by using option width.