RTD: instructions for OS-HPXML subtree

docs/read_the_docs/source/advanced_tutorial/increasing_upgrade_options.rst

@@ -5,8 +5,9 @@ To allow more options per upgrade, increase the value returned by the following
 
 .. code::
 
-  def self.NumApplyUpgradeOptions
-    return 25
-  end
+  module Constants
+    NumApplyUpgradeOptions = 25
+    NumApplyUpgradesCostsPerOption = 2
+  ...
 
 Then run ``openstudio tasks.rb update_measures``. See :doc:`running_tasks` for instructions on how to run tasks.

docs/read_the_docs/source/advanced_tutorial/index.rst

@@ -12,9 +12,9 @@ If your changes are intended to be merged into the ``develop`` branch of the `Re
 .. toctree::
    :maxdepth: 2
 
-   installer_setup
    running_tasks
    options_lookup
    increasing_upgrade_options
    upgrade_scenario_config
    heat_pump_upgrades
+   openstudio_hpxml

docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst

@@ -0,0 +1,43 @@
+OpenStudio-HPXML
+================
+
+ResStock contains a `git subtree <https://www.atlassian.com/git/tutorials/git-subtree>`_ to the `OpenStudio-HPXML <https://github.com/NREL/OpenStudio-HPXML>`_ repository.
+The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the files contained in OpenStudio-HPXML.
+As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development.
+It may also be helpful to test an OpenStudio-HPXML branch using a branch of ResStock.
+In either case, the subtree at ``resources/hpxml-measures`` can be updated using a set of simple commands.
+
+.. _latest-os-hpxml:
+
+Syncing OpenStudio-HPXML
+------------------------
+
+For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``master`` branch, branch off of ``develop`` (e.g., with branch name ``latest-os-hpxml``), and then enter the following command:
+
+.. code:: bash
+
+  $ openstudio tasks.rb update_resources
+
+See :doc:`running_tasks` for more information and context about running tasks.
+
+.. _branch-os-hpxml:
+
+Testing OpenStudio-HPXML
+------------------------
+
+For pulling in and testing a specific OpenStudio-HPXML branch, first create a test branch in ResStock. Then enter the following command:
+
+.. code:: bash
+
+  $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git <branch_name> --squash
+
+.. _other-updates:
+
+Other Updates
+-------------
+
+After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved:
+- manually edit measures/ResStockArguments/measure.rb and run ``openstudio tasks.rb update_measures`` to force the measure.xml to be regenerated
+- update options lookup with any new ResStockArguments arguments
+- address any input/output data dictionary updates at ``resources/data/dictionary``
+- TODO

docs/read_the_docs/source/advanced_tutorial/options_lookup.rst

@@ -5,8 +5,8 @@ The ``options_lookup.tsv`` file, found in the ``resources`` folder, specifies ma
 For example, if the distribution of cooling system types in ``HVAC Cooling Efficiency.tsv`` has ``Option=AC, SEER 13`` and ``Option=AC, SEER 15``, but you want to include a ``Option=AC, SEER 17`` option, you would add that option as a column and then create a corresponding row in ``options_lookup.tsv``.
 Updates to this file will allow you to avoid hitting the following types of integrity check errors:
 
- - :ref:`Could not find parameter and option <could-not-find-parameter-and-option>`
- - :ref:`Required argument not provided <required-argument-not-provided>`
+- :ref:`Could not find parameter and option <could-not-find-parameter-and-option>`
+- :ref:`Required argument not provided <required-argument-not-provided>`
 
 .. _integrity-check-errors:
 

docs/read_the_docs/source/advanced_tutorial/running_tasks.rst

@@ -32,6 +32,8 @@ Use ``openstudio tasks.rb update_measures`` to apply rubocop auto-correct to mea
   Updating measure.xmls...
   Done.
 
+.. _update-resources:
+
 Update Resources
 ----------------
 
@@ -81,20 +83,3 @@ Run ``openstudio tasks.rb download_weather`` to download available EPW weather f
   Downloading /files/156/BuildStock_TMY3_FIPS.zip (  2%) 
   Downloading /files/156/BuildStock_TMY3_FIPS.zip (  3%)
   ...
-
-.. rakefile:
-
-Rakefile
---------
-
-Once you have completed instructions found in :doc:`installer_setup`, you can then use the `Rakefile <https://github.com/NREL/resstock/blob/develop/Rakefile>`_ contained at the top level of this repository. You can run rake task(s) for :ref:`performing integrity checks on project inputs <integrity-checks>` as well as executing various tests.
-
-Run ``rake -T`` to see the list of possible rake tasks. The ``-T`` is replaced with the chosen task.
-
-.. code:: bash
-
-  $ rake -T
-  rake unit_tests:integrity_check_tests     # Run tests for integrity_check_t...
-  rake unit_tests:measure_tests             # Run tests for measure_tests
-  rake unit_tests:project_integrity_checks  # Run tests for project_integrity...
-  rake workflow:analysis_tests              # Run tests for analysis_tests