prep for release

- updating versions to 2.2 - documentation additions/changes fixes #95
hpxmlwg · Aug 3, 2016 · 24be0c8 · 24be0c8
1 parent 3f7827f
commit 24be0c8
Show file tree

Hide file tree

Showing 18 changed files with 134 additions and 40 deletions.
diff --git a/examples/audit.xml b/examples/audit.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
     <XMLTransactionHeaderInformation>
         <XMLType/>
         <XMLGeneratedBy>Super-duper audit software v1.0</XMLGeneratedBy>

diff --git a/examples/bpi2101.xml b/examples/bpi2101.xml
@@ -1,4 +1,4 @@
-<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
     <XMLTransactionHeaderInformation>
         <XMLType>BPI-2101</XMLType>
         <XMLGeneratedBy>Noel</XMLGeneratedBy>

diff --git a/examples/upgrade.xml b/examples/upgrade.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+<HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
     <XMLTransactionHeaderInformation>
         <XMLType/>
         <XMLGeneratedBy>Joe</XMLGeneratedBy>

diff --git a/guide/source/conf.py b/guide/source/conf.py
@@ -32,7 +32,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.pngmath',
+    'sphinx.ext.mathjax',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,16 +52,16 @@
 
 # General information about the project.
 project = u'HPXML Implementation Guide'
-copyright = u'2015, Noel Merket (NREL), Gavin Hastings (Tierra Resource Consultants, LLC)'
+copyright = u'2016, Noel Merket (NREL), Gavin Hastings (Tierra Resource Consultants, LLC)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.1' # should match hpxml version
+version = '2.2' # should match hpxml version
 # The full version, including alpha/beta/rc tags.
-release = '2.1'
+release = '2.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -286,7 +286,7 @@
 epub_title = u'HPXML Implementation Guide'
 epub_author = u'Noel Merket (NREL)'
 epub_publisher = u'Noel Merket (NREL)'
-epub_copyright = u'2014, Noel Merket (NREL)'
+epub_copyright = u'2016, Noel Merket (NREL)'
 
 # The basename for the epub file. It defaults to the project name.
 #epub_basename = u'HPXML Implementation Guide'

diff --git a/guide/source/program_administrator/data_validation.rst b/guide/source/program_administrator/data_validation.rst
@@ -45,6 +45,21 @@ properly, you can burn out your users and create contractor dissatisfaction.
 This, of course, is not an observation exclusive to HPXML, but a best practice
 in any software implementation in general.
 
+.. _toolbox:
+
+HPXML Toolbox
+*************
+
+To assist in validation, NREL provides an `HPXML Toolbox`_ website that includes
+a schema validator, use case validator, a collapsable tree view of HPXML data,
+and a web API that can be incorportated into software workflows. The tool is
+useful to both software developers to test their implementation against the
+known use cases. It is also helpful for program administrators to see what data
+is in an HPXML file and what additional data would be required to meet any of
+the use cases.
+
+.. _HPXML Toolbox: https://hpxml.nrel.gov/
+
 Phasing of Validation
 *********************
 

diff --git a/guide/source/program_administrator/identify_data_needs.rst b/guide/source/program_administrator/identify_data_needs.rst
@@ -141,9 +141,13 @@ for HPXML program implementation.  Programs can then forward the tool to the
 implementation team, trade allies and software providers, giving them clear
 guidance on the requirements  for HPXML Implementation with your program.
 
-.. todo::
+.. raw:: html
 
-    YouTube video here.
+    <iframe width="640" height="360" src="https://www.youtube.com/embed/vmfU1ytzMfc" frameborder="0" allowfullscreen></iframe>
+
+.. raw:: latex
+
+    \par\href{https://youtu.be/vmfU1ytzMfc}{YouTube: HPXML Data Selection Tool Tutorial}\par
 
 Additional details about the data structure and standard data sets are provided
 in the sections below.
@@ -240,6 +244,8 @@ cases that have been developed to date. Each use case only uses a fraction of
 the data points that the HPXML standard can support. Over time, more use cases
 will be developed to meet market needs.
 
+.. _audit-use-case-defn:
+
 Audit Use Case
 ==============
 
@@ -257,6 +263,8 @@ can be found in the software developer guide at
 
 .. _HPXML GitHub repository: https://github.com/hpxmlwg/hpxml/tree/hpxmlguide/examples
 
+.. _upgrade-use-case-defn:
+
 Upgrade Use Case
 ================
 
@@ -274,6 +282,8 @@ program needs.
 The upgrade use case HPXML file is very similar to the audit use case. The
 differences are detailed in :doc:`/software_developer/usecases/auditupgrade`. 
 
+.. _hescore-use-case-defn:
+
 Home Energy Score Use Case
 ==========================
 
@@ -292,7 +302,9 @@ integration with the Home Energy Score API, see
 A full list of HPXML data elements that can currently be incorporated into use
 cases is available in the `online schema documentation`_.
 
-.. _online schema documentation: http://hpxmlwg.github.io/hpxml/schemadoc/hpxml-2.1.0/index.html
+.. _online schema documentation: http://hpxmlwg.github.io/hpxml/schemadoc/hpxml-2.2.0/index.html
+
+.. _bpi2101-use-case-defn:
 
 BPI – 2101 Certificate of Completion Use Case
 =============================================

diff --git a/guide/source/software_developer/devtools.rst b/guide/source/software_developer/devtools.rst
@@ -0,0 +1,34 @@
+Development Tools
+#################
+
+Data Selection Tool
+*******************
+
+Program administrators are being instructed to use the :ref:`datatool` to
+determine and communicate the intersection of :doc:`usecases/index` they're
+interested in as well as any additional elements to collect and require.
+Elements beyond established use cases are highlighted in red. In the
+spreadsheeet, elements required by a use case will be more prominent (black font
+color instead of light grey). Elements required in addition to specified use
+cases will be highlighted in red. All together, it should provide a complete
+list of data elements required to either provide or process.
+
+HPXML Toolbox
+*************
+
+To facilitate the adoption of the HPXML standard use cases, NREL has developed
+the `HPXML Toolbox`_. The toolbox provides a schema validator plus use case
+validator. Submitting an HPXML file will perform the following steps:
+
+#. Validation of the file against HPXML schema and determination of schema version.
+#. Validation against each of the standard use cases including output describing
+   any missing elements required to meet a particular use case. 
+#. Display of HPXML file in collapsable tree form.
+
+The validation functionality is available as a `website`_ for testing and
+viewing individual files, or as a `web service API`_ that allows the validation
+to be called as part of a software workflow. 
+
+.. _website: https://hpxml.nrel.gov/validator/
+.. _web service API: https://hpxml.nrel.gov/api/
+.. _HPXML Toolbox: https://hpxml.nrel.gov
diff --git a/guide/source/software_developer/index.rst b/guide/source/software_developer/index.rst
@@ -8,5 +8,5 @@ Software Developer Guide
    versioning
    structure
    references
+   devtools
    usecases/index
-
diff --git a/guide/source/software_developer/references.rst b/guide/source/software_developer/references.rst
@@ -45,7 +45,7 @@ to.
    :emphasize-lines: 19,25
 
    <?xml version="1.0" encoding="UTF-8"?>
-   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
        <XMLTransactionHeaderInformation>
            <XMLType></XMLType>
            <XMLGeneratedBy></XMLGeneratedBy>
@@ -92,7 +92,7 @@ to have a way to indicate that they are the same item.
    :emphasize-lines: 19,34
 
    <?xml version="1.0" encoding="UTF-8"?>
-   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
        <XMLTransactionHeaderInformation>
            <XMLType></XMLType>
            <XMLGeneratedBy></XMLGeneratedBy>

diff --git a/guide/source/software_developer/usecases/auditupgrade.rst b/guide/source/software_developer/usecases/auditupgrade.rst
@@ -5,8 +5,8 @@ Audit-Upgrade
 
 The audit-upgrade use case covers two scenarios:
 
-#. A baseline building with a proposed work scope 
-#. A baseline building with a completed work scope
+#. A baseline building with a proposed work scope (see :ref:`audit-use-case-defn`)
+#. A baseline building with a completed work scope (see :ref:`upgrade-use-case-defn`)
 
 Both scenarios describe a pre- and post-upgrade building and the actions
 (measures) that occur between the two states to make the difference. To achieve
@@ -36,6 +36,7 @@ include their name and phone number as shown.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml 
+   :dedent: 4
    :lines: 34-47
    :emphasize-lines: 6-7,10
 
@@ -60,7 +61,8 @@ of ``audit``.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml 
-   :lines: 48-49,60-62,280
+   :dedent: 4
+   :lines: 48-49,60-62,286
    :emphasize-lines: 4
 
 Many items within the building require a unique ``SystemIdentifier`` element.
@@ -71,7 +73,8 @@ For example, the water heater in the pre-upgrade building has an id of ``dhw1``.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :lines: 222-228
+   :dedent: 20
+   :lines: 228-234
    :emphasize-lines: 2
 
 .. _postupgrade:
@@ -109,7 +112,8 @@ pre-upgrade water heater and indicate it is indeed the same equipment.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :lines: 455-461
+   :dedent: 20
+   :lines: 467-473
    :emphasize-lines: 2
 
 .. note::
@@ -131,7 +135,8 @@ building.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :lines: 566-571,588-589,610-612
+   :dedent: 4
+   :lines: 578-586,603-604,625-627
    :emphasize-lines: 2,4-5
 
 Energy Savings
@@ -142,7 +147,8 @@ measured energy use and savings achieved in an upgrade.
 
 .. literalinclude:: /../../examples/audit.xml
    :language: xml
-   :lines: 571-588
+   :dedent: 12
+   :lines: 586-603
 
 .. note::
 
@@ -162,22 +168,25 @@ The measure cost is also included.
 From the example file, this measure
 
 .. literalinclude:: /../../examples/audit.xml 
-   :language: xml 
-   :lines: 600-609 
+   :language: xml
+   :dedent: 16
+   :lines: 615-624 
    :emphasize-lines: 7,9
 
 replaces this furnace in the pre-upgrade building
 
 .. literalinclude:: /../../examples/audit.xml 
    :language: xml 
-   :lines: 148-161 
+   :dedent: 24
+   :lines: 154-167 
    :emphasize-lines: 2
 
 with this one.
 
 .. literalinclude:: /../../examples/audit.xml 
-   :language: xml 
-   :lines: 381-394 
+   :language: xml
+   :dedent: 24
+   :lines: 393-406
    :emphasize-lines: 2
 
 
diff --git a/guide/source/software_developer/usecases/bpi2101.rst b/guide/source/software_developer/usecases/bpi2101.rst
@@ -0,0 +1,21 @@
+BPI – 2101 Certificate of Completion
+####################################
+
+This use case contains data that has the intent of informing real estate
+transactions (See :ref:`bpi2101-use-case-defn`). It is likely the most
+complicated use case and contains each of the following :ref:`building-node`
+nodes.
+
+* Pre-upgrade
+* Proposed workscope
+* Post-upgrade
+
+Two :ref:`project-node` nodes are included as well that describe the proposed
+project and the completed project. It can be thought of as a combination of the
+:doc:`Audit and Upgrade <auditupgrade>` use cases. 
+
+Finally, :ref:`consumption-node` and :ref:`utility-node` nodes are also included
+to provide a utility billing history.
+
+See the ``examples/bpi2101.xml`` document for more details on what data elements
+are included.
diff --git a/guide/source/software_developer/usecases/example1.xml b/guide/source/software_developer/usecases/example1.xml
@@ -2,7 +2,7 @@
 <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.1">
+ schemaVersion="2.2">
     <XMLTransactionHeaderInformation>
         <XMLType></XMLType>
         <XMLGeneratedBy></XMLGeneratedBy>

diff --git a/guide/source/software_developer/usecases/hescore.rst b/guide/source/software_developer/usecases/hescore.rst
@@ -11,12 +11,14 @@ requires data inputs to be submitted in terms of the data model set forth by
 |hescore|. Therefore, any users of the |hescore| API must translate their data
 into the appropriate location and representation in the |hescore| input array. 
 
-The latest version of the |hescore| API provides the capability for an HPXML
-import. This receives an HPXML file as input and translates the user-specified
-:ref:`building-node` element (whether pre- or post-upgrade) into corresponding
-|hescore| inputs and populates the |hescore| input array. By using this import
-capability software developers can leverage their investment in HPXML to provide
-|hescore| functionality at a minimum incremental development cost.
+The |hescore| API provides the capability for an HPXML import. This receives an
+HPXML file as input and translates the user-specified :ref:`building-node`
+element (whether pre- or post-upgrade) into corresponding |hescore| inputs and
+populates the |hescore| input array. By using this import capability software
+developers can leverage their investment in HPXML to provide |hescore|
+functionality at a minimum incremental development cost.
+
+See :ref:`hescore-use-case-defn` for additional information.
 
 |hescore| API
 *************

diff --git a/guide/source/software_developer/usecases/index.rst b/guide/source/software_developer/usecases/index.rst
@@ -6,4 +6,4 @@ Use Cases
 
    auditupgrade
    hescore
-
+   bpi2101
diff --git a/guide/source/software_developer/versioning.rst b/guide/source/software_developer/versioning.rst
@@ -3,7 +3,7 @@ Versioning
 
 The HPXML schemas follow the `Semantic Versioning v2.0 <http://semver.org/>`_
 specification. The version numbers follow a pattern of :ref:`major-version`.
-:ref:`minor-version`. :ref:`patch-version` (i.e. 2.1.0). 
+:ref:`minor-version`. :ref:`patch-version` (i.e. 2.2.0). 
 
 The first element of ``HPXML.xsd`` will indicate the version of the schema via
 the ``version`` attribute. Note that when referencing a version, the patch
@@ -12,15 +12,15 @@ number is assumed to be zero if it is omitted.
 .. code-block:: xml
 
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://hpxmlonline.com/2014/6"
-    targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.1"> 
+    targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.2"> 
 
 Additionally, starting with version 2.0, the version of the schema used is
 required in the ``schemaVersion`` attribute on the root element of every
 document. 
 
 .. code-block:: xml
 
-   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.1">
+   <HPXML xmlns="http://hpxmlonline.com/2014/6" schemaVersion="2.2">
     
 .. _major-version:
 

diff --git a/schemas/BaseElements.xsd b/schemas/BaseElements.xsd
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://hpxmlonline.com/2014/6"
-	targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.1">
+	targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.2">
 	<xs:include schemaLocation="HPXMLDataTypes.xsd"/>
 	<xs:element name="XMLTransactionHeaderInformation">
 		<xs:annotation>

diff --git a/schemas/HPXML.xsd b/schemas/HPXML.xsd
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://hpxmlonline.com/2014/6"
-    targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.1">
+    targetNamespace="http://hpxmlonline.com/2014/6" elementFormDefault="qualified" version="2.2">
     <xs:include schemaLocation="BaseElements.xsd"/>
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ Use Cases

		auditupgrade
		hescore

		bpi2101