Merge pull request #121 from NREL/task/build-documentation

.gitignore

@@ -1,7 +1,7 @@
 *.DS_Store
 .idea
 gbxmls/Cases/
-/installer_staging/
+/installer_staging*
 measures/*/output_models/
 measures/*/tests/output
 node_modules/

Gemfile

@@ -1,18 +1,13 @@
 # frozen_string_literal: true
 
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gem 'ansi'
-gem 'openstudio-standards'
-gem 'openstudio-api-stubs'
-gem 'openstudio-standards'
+gem 'builder'
 gem 'minitest'
 gem 'minitest-reporters'
+gem 'openstudio-api-stubs'
+gem 'openstudio-standards'
 gem 'rake'
-gem 'builder'
-
-# DLM: currently rely on embedded gem versions for these
-#gem 'openstudio-standards'
-#gem 'openstudio-workflow'

Gemfile.lock

@@ -2,21 +2,19 @@ GEM
   remote: http://rubygems.org/
   specs:
     ansi (1.5.0)
-    builder (3.2.3)
-    minitest (5.11.3)
-    minitest-reporters (1.3.5)
+    builder (3.2.4)
+    minitest (5.18.0)
+    minitest-reporters (1.6.0)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
     openstudio-api-stubs (0.1.0)
     openstudio-standards (0.2.9)
-    rake (12.3.1)
-    ruby-progressbar (1.10.0)
+    rake (13.0.6)
+    ruby-progressbar (1.13.0)
 
 PLATFORMS
-  mswin64
-  ruby
   x64-mingw32
 
 DEPENDENCIES
@@ -29,4 +27,4 @@ DEPENDENCIES
   rake
 
 BUNDLED WITH
-   1.16.6
+   2.1.4

README.md

@@ -1,9 +1,47 @@
-# gbxml-to-openstudio
+# gbXML to OpenStudio
+
 This repository is intended to develop code that uses one or more advanced gbXML import measures to take gbXML to OSM translation beyond what is covered by GbXMLReverseTranslator in the OpenStudio C++ code.
-
- The initial commit includes the following directories.
- * gbxmls - example gbXML files
- * measures - existing and new measures used to translate and test gbXML to OSM translation
- * workflows - OSW files that using the OpenStudio CLI run the gbXML to OSM translation workflow measures, forward translate OSM to IDF, and run EnergyPlus
- * seeds - contains seed models used by one or more OSW files
- * weather - contain one or more weather files used by OSW files
+
+## Directories
+
+- `gbxmls` - example gbXML files, and complex models for regression testing
+- `measures` - existing and new measures used to translate and test gbXML to OSM translation
+- `seeds` - contains seed models used by one or more OSW workflows
+- `weather` - contains weather files used by OSW workflows
+- `workflows` - OSW workflow files that using the OpenStudio CLI run the gbXML to OSM translation workflow measures, forward translate OSM to IDF, and run EnergyPlus
+
+## Configure Development Environment
+1. Install the desired version of OpenStudio (Revit currently uses [OpenStudio v3.4.0](https://github.com/NREL/OpenStudio/releases/download/v3.4.0/OpenStudio-3.4.0+4bd816f785-Windows.exe))
+2. Install the *custom* version of EnergyPlus corresponding to the OpenStudio version (currently [EnergyPlus 22.1.0 For Revit](https://github.com/NREL/openstudio-revit-releases/releases/tag/v22.1.0))
+   1. If the version of EnergyPlus hasn't been built yet, follow the instructions in the [openstudio-revit-releases](https://github.com/NREL/openstudio-revit-releases/) repo to build one
+   2. Change the default install location so that it can be installed alongside the official release if necessary (e.g. `C:\EnergyPlusV22-1-0-revit`)
+3. Install [Ruby v2.7 for Windows](https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-2.7.8-1/rubyinstaller-2.7.8-1-x64.exe) (devkit shouldn't be necessary)
+   1. Open a command prompt in the `gbxml-to-openstudio` directory
+   2. Run `gem install bundler`
+   3. Run `bundler install`
+4. Install [7-Zip](https://www.7-zip.org/download.html)
+5. Install the latest [Advanced Installer](https://www.advancedinstaller.com/download.html)
+
+## Building Signed Installers
+1. Pull the latest code
+2. Update `CHANGELOG.md` to reflect changes included in the new release
+3. If a previous `installer_staging` directory exists move it to `installer_stating.old`
+4. Run `rake build_installer`, which copies files to the `installer_staging` directory (`bundler install` may be necessary as well if the gem dependencies have changed). Ensure that any untracked files in the following directories are removed prior to running.
+   - `measures`
+   - `seeds`
+   - `weather`
+   - `workflows`
+5. Zip the `installer_staging` directory using 7-Zip, and drag the resulting zip file to the `code-signing-client.exe` executable. 7-Zip is necessary because Windows is unable to compress files with unicode names
+6. Once `installer_staging.signed.zip` has finished downloading simply extract the contents back into the `installer_staging` directory, replacing the original files
+7. Diff the `installer_staging.old` and `installer_staging` directories
+    1. If any files were *added* they must be manually dragged into the Advanced Installer file tree
+    2. If any files were _removed_ they must be manually deleted from the Advanced Installer file tree
+8. In _Advanced Installer_, with the `Product Details` tab active, increment the patch version (e.g. `1.1.5` -> `1.1.6`) and hit _Save_
+    1. When prompted to generate a new product code click `Generate new`, and save again
+9. In _Advanced Installer_, with the `Product Details` tab active, click `Build` in the ribbon
+10. Once the build has successfully completed, browse to the `OpenStudio CLI For Revit 202X-SetupFiles/` directory, and drag the newly created msi to the `code-signing-client.exe` executable
+11. After the signed msi has been downloaded delete the original and remove the `.signed` suffix from the filename
+12. Upload the signed msi installer to the `openstudio-cli-4r` S3 bucket. Append the filename to `https://openstudio-cli-4r.s3.amazonaws.com/` to download
+13. Delete the `installer_staging.old` directory if it was created
+14. Commit the `*.aip` and `CHANGELOG.md` file changes
+15. Create a git tag on the new commit matching the updated release version

Rakefile

@@ -27,7 +27,7 @@ task :build_installer do
   staging_dir = File.join(root_dir, 'installer_staging')
   os_install_dir = 'C:\openstudio-3.4.0'
   openstudio_cli = File.join(os_install_dir, 'bin', 'openstudio.exe')
-  energyplus_dir = 'C:\EnergyPlusV22-1-0-python'
+  energyplus_dir = 'C:\EnergyPlusV22-1-0-revit'
 
   unless File.exists?(os_install_dir)
     puts "#{os_install_dir} does not exist"