Merge pull request #328 from hpxmlwg/example_files_etc

Example files and prep for v3.1

.gitignore

@@ -5,3 +5,5 @@ guide/build
 .idea
 .DS_Store
 .vscode
+__pycache__/
+*.pyc

guide/source/conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.3' # should match hpxml version
+version = '3.1' # should match hpxml version
 # The full version, including alpha/beta/rc tags.
-release = '2.3'
+release = '3.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

guide/source/overview.rst

@@ -60,7 +60,7 @@ The HPXML Working Group can be a valuable resource for program administrators, i
 Versioning
 ==========
 
-The HPXML schema follows the `Semantic Versioning 2.0 specification <http://semver.org/>`_. The version numbers follow a pattern of Major, Minor, and Patch (e.g., 2.3.0). The major version number is incremented when the schemas are changed in a manner that is incompatible with previous versions. Examples of changes that require a major version change include renaming elements, removing elements, moving elements, and removing enumerations.
+The HPXML schema follows the `Semantic Versioning 2.0 specification <http://semver.org/>`_. The version numbers follow a pattern of Major, Minor, and Patch (e.g., 3.1.0). The major version number is incremented when the schemas are changed in a manner that is incompatible with previous versions. Examples of changes that require a major version change include renaming elements, removing elements, moving elements, and removing enumerations.
 
 The minor version number is incremented when the schemas are changed in a manner that is backwards compatible with previous versions that share the same major version. In other words, a document created in a previous version of the schema will also validate against the new schema. Examples of changes that require a minor version change include adding elements, adding enumerations, and changing the annotation in the schema for an element. 
 

guide/source/software_developer/idref.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<HPXML xmlns="http://hpxmlonline.com/2019/10" schemaVersion="3.1">
+    <XMLTransactionHeaderInformation>
+        <XMLType></XMLType>
+        <XMLGeneratedBy></XMLGeneratedBy>
+        <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
+        <Transaction>create</Transaction>
+    </XMLTransactionHeaderInformation>
+    <SoftwareInfo/>
+    <Building>
+        <BuildingID id="bldg1"/>
+        <ProjectStatus>
+            <EventType>audit</EventType>
+        </ProjectStatus>
+        <BuildingDetails>
+            <Enclosure>
+                <Walls>
+                    <Wall>
+                        <SystemIdentifier id="wall1"/>
+                    </Wall>
+                </Walls>
+                <Windows>
+                    <Window>
+                        <SystemIdentifier id="window1"/>
+                        <AttachedToWall idref="wall1"/>
+                    </Window>
+                </Windows>
+            </Enclosure>
+        </BuildingDetails>
+    </Building>
+</HPXML>

guide/source/software_developer/references.rst

@@ -40,40 +40,9 @@ When an element needs to reference another element it uses an
 which ensures that the id referenced exists somewhere within the document. One
 simple example of this is how a window can reference the wall to which it is attached.
 
-.. code-block:: xml
-   :emphasize-lines: 19,25
-
-   <?xml version="1.0" encoding="UTF-8"?>
-   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.3">
-       <XMLTransactionHeaderInformation>
-           <XMLType></XMLType>
-           <XMLGeneratedBy></XMLGeneratedBy>
-           <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
-           <Transaction>create</Transaction>
-       </XMLTransactionHeaderInformation>
-       <SoftwareInfo/>
-       <Building>
-           <BuildingID id="bldg1"/>
-           <ProjectStatus>
-               <EventType>audit</EventType>
-           </ProjectStatus>
-           <BuildingDetails>
-               <Enclosure>
-                   <Walls>
-                       <Wall>
-                           <SystemIdentifier id="wall1"/>
-                       </Wall>
-                   </Walls>
-                   <Windows>
-                       <Window>
-                           <SystemIdentifier id="window1"/>
-                           <AttachedToWall idref="wall1"/>
-                       </Window>
-                   </Windows>
-               </Enclosure>
-           </BuildingDetails>
-       </Building>
-   </HPXML>
+.. literalinclude:: idref.xml
+    :language: xml
+    :emphasize-lines: 19,25
 
 .. _sameas:
 
@@ -87,50 +56,9 @@ buildings between the pre- and post-upgrade ``Building`` nodes. Each
 affect some of the components. For components that do not change it is useful
 to have a way to indicate that they are the same item. 
 
-.. code-block:: xml
-   :emphasize-lines: 19,34
-
-   <?xml version="1.0" encoding="UTF-8"?>
-   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.3">
-       <XMLTransactionHeaderInformation>
-           <XMLType></XMLType>
-           <XMLGeneratedBy></XMLGeneratedBy>
-           <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
-           <Transaction>create</Transaction>
-       </XMLTransactionHeaderInformation>
-       <SoftwareInfo/>
-       <Building>
-           <BuildingID id="bldg1"/>
-           <ProjectStatus>
-               <EventType>audit</EventType>
-           </ProjectStatus>
-           <BuildingDetails>
-               <Enclosure>
-                   <Walls>
-                       <Wall>
-                           <SystemIdentifier id="wall1"/>
-                       </Wall>
-                   </Walls>
-               </Enclosure>
-           </BuildingDetails>
-       </Building>
-       <Building>
-           <BuildingID id="bldg1post"/>
-           <ProjectStatus>
-               <EventType>proposed workscope</EventType>
-           </ProjectStatus>
-           <BuildingDetails>
-               <Enclosure>
-                   <Walls>
-                       <Wall>
-                           <SystemIdentifier id="wall1post" sameas="wall1"/>
-                       </Wall>
-                   </Walls>
-               </Enclosure>
-           </BuildingDetails>
-       </Building>
-   </HPXML>
-
+.. literalinclude:: sameas.xml
+    :language: xml
+    :emphasize-lines: 19,34
 
 Inter-Document References
 *************************

guide/source/software_developer/sameas.xml

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<HPXML xmlns="http://hpxmlonline.com/2019/10" schemaVersion="3.1">
+    <XMLTransactionHeaderInformation>
+        <XMLType></XMLType>
+        <XMLGeneratedBy></XMLGeneratedBy>
+        <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
+        <Transaction>create</Transaction>
+    </XMLTransactionHeaderInformation>
+    <SoftwareInfo/>
+    <Building>
+        <BuildingID id="bldg1"/>
+        <ProjectStatus>
+            <EventType>audit</EventType>
+        </ProjectStatus>
+        <BuildingDetails>
+            <Enclosure>
+                <Walls>
+                    <Wall>
+                        <SystemIdentifier id="wall1"/>
+                    </Wall>
+                </Walls>
+            </Enclosure>
+        </BuildingDetails>
+    </Building>
+    <Building>
+        <BuildingID id="bldg1post"/>
+        <ProjectStatus>
+            <EventType>proposed workscope</EventType>
+        </ProjectStatus>
+        <BuildingDetails>
+            <Enclosure>
+                <Walls>
+                    <Wall>
+                        <SystemIdentifier id="wall1post" sameas="wall1"/>
+                    </Wall>
+                </Walls>
+            </Enclosure>
+        </BuildingDetails>
+    </Building>
+</HPXML>

guide/source/software_developer/usecases/auditupgrade.rst

@@ -22,7 +22,8 @@ who is proposing and or completing the work), company and the email address.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :lines: 13-33
+   :lines: 12-32
+   :dedent: 2
    :emphasize-lines: 11-12,15
 
 Customer
@@ -33,8 +34,9 @@ include the customer's name and phone number.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml 
-   :dedent: 4
-   :lines: 34-47
+   :dedent: 2
+   :start-at: <Customer>
+   :end-at: </Customer>
    :emphasize-lines: 6-7,10
 
 Building
@@ -57,8 +59,8 @@ of ``audit``.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml 
-   :dedent: 4
-   :lines: 48-49,60-62,286
+   :dedent: 2
+   :lines: 47-48,59-61,302
    :emphasize-lines: 4
 
 Many items within the building require a unique ``SystemIdentifier`` element.
@@ -69,8 +71,8 @@ For example, the water heater in the pre-upgrade building has an id of ``dhw1``.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :dedent: 20
-   :lines: 228-234
+   :dedent: 10
+   :lines: 244-250
    :emphasize-lines: 2
 
 .. _postupgrade:
@@ -105,8 +107,8 @@ pre-upgrade water heater and indicate it is indeed the same equipment.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :dedent: 20
-   :lines: 467-473
+   :dedent: 10
+   :lines: 500-506
    :emphasize-lines: 2
 
 .. note::
@@ -122,15 +124,14 @@ In this paradigm, the :ref:`preupgrade` and :ref:`postupgrade` building elements
 describe the state of the building at points in time. The ``Project`` element
 describes what was done, or is planning to be done, to the building to get from one scenario to another. 
 
-The ``ProjectSystemIdentifiers`` are used to reference the pre- and post-
-building ids. The redundant ``BuildingID`` element should reference the post-
-building.
+``PreBuildingID`` and ``PostBuildingID`` are used to reference the pre- and post-
+building ids, respectively.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :dedent: 4
-   :lines: 578-586,603-604,625-627
-   :emphasize-lines: 2,4-5
+   :dedent: 2
+   :lines: 611-618,664-665
+   :emphasize-lines: 2-4
 
 Energy Savings
 ==============
@@ -140,8 +141,9 @@ measured energy use and savings achieved in an upgrade.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :dedent: 12
-   :lines: 586-603
+   :dedent: 6
+   :start-at: <EnergySavingsInfo>
+   :end-at: </EnergySavingsInfo>
 
 .. note::
 
@@ -163,22 +165,22 @@ From the example file below, this measure replaces this furnace in the pre-upgra
 
 .. literalinclude:: /../../examples/audit.xml 
    :language: xml
-   :dedent: 16
-   :lines: 615-624 
-   :emphasize-lines: 7,9
+   :dedent: 8
+   :lines: 651-662
+   :emphasize-lines: 7,10
 
 
 .. literalinclude:: /../../examples/audit.xml 
    :language: xml 
-   :dedent: 24
-   :lines: 154-167 
+   :dedent: 12
+   :lines: 170-183 
    :emphasize-lines: 2
 
 
 .. literalinclude:: /../../examples/audit.xml 
    :language: xml
-   :dedent: 24
-   :lines: 393-406
+   :dedent: 12
+   :lines: 426-439
    :emphasize-lines: 2
 
 

guide/source/software_developer/usecases/example1.xml

@@ -1,43 +1,39 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<HPXML xmlns="http://hpxmlonline.com/2014/6"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://hpxmlonline.com/2014/6 ../schemas/HPXML.xsd"
- schemaVersion="2.3">
-    <XMLTransactionHeaderInformation>
-        <XMLType></XMLType>
-        <XMLGeneratedBy></XMLGeneratedBy>
-        <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
-        <Transaction>create</Transaction>
-    </XMLTransactionHeaderInformation>
-    <SoftwareInfo/>
-    <Building>
-        <BuildingID id="bldg1"/>
-        <ProjectStatus>
-            <EventType>audit</EventType>
-        </ProjectStatus>
-        <BuildingDetails>
-            <Enclosure>
-                <Walls>
-                    <Wall>
-                        <SystemIdentifier id="wall1"/>
-                    </Wall>
-                </Walls>
-            </Enclosure>
-        </BuildingDetails>
-    </Building>
-    <Building>
-        <BuildingID id="bldg1post"/>
-        <ProjectStatus>
-            <EventType>proposed workscope</EventType>
-        </ProjectStatus>
-        <BuildingDetails>
-            <Enclosure>
-                <Walls>
-                    <Wall>
-                        <SystemIdentifier id="wall1post" sameas="wall1"/>
-                    </Wall>
-                </Walls>
-            </Enclosure>
-        </BuildingDetails>
-    </Building>
+<HPXML xmlns="http://hpxmlonline.com/2019/10" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://hpxmlonline.com/2014/6 ../schemas/HPXML.xsd" schemaVersion="3.1">
+  <XMLTransactionHeaderInformation>
+    <XMLType/>
+    <XMLGeneratedBy/>
+    <CreatedDateAndTime>2014-09-03T16:06:24Z</CreatedDateAndTime>
+    <Transaction>create</Transaction>
+  </XMLTransactionHeaderInformation>
+  <SoftwareInfo/>
+  <Building>
+    <BuildingID id="bldg1"/>
+    <ProjectStatus>
+      <EventType>audit</EventType>
+    </ProjectStatus>
+    <BuildingDetails>
+      <Enclosure>
+        <Walls>
+          <Wall>
+            <SystemIdentifier id="wall1"/>
+          </Wall>
+        </Walls>
+      </Enclosure>
+    </BuildingDetails>
+  </Building>
+  <Building>
+    <BuildingID id="bldg1post"/>
+    <ProjectStatus>
+      <EventType>proposed workscope</EventType>
+    </ProjectStatus>
+    <BuildingDetails>
+      <Enclosure>
+        <Walls>
+          <Wall>
+            <SystemIdentifier id="wall1post" sameas="wall1"/>
+          </Wall>
+        </Walls>
+      </Enclosure>
+    </BuildingDetails>
+  </Building>
 </HPXML>