Updates documentation

NREL · Aug 31, 2018 · 7a45d72 · 7a45d72
1 parent 18ed818
commit 7a45d72
Show file tree

Hide file tree

Showing 11 changed files with 246 additions and 228 deletions.
diff --git a/.yardopts b/.yardopts
@@ -1,6 +1,15 @@
 --main docs/Home.md
 --embed-mixins
---exclude lib/openstudio-standards/prototypes/common/buildings/Prototype.all_buildings.rb
+--exclude lib/openstudio-standards/prototypes/common/buildings/Prototype.*.rb
+--exclude lib/openstudio-standards/utilities/convert_costing_constructions.rb
+--exclude lib/openstudio-standards/prototypes/common/do_not_edit_metaclasses.rb
+--exclude lib/openstudio-standards/weather/Weather.Model.rb
+--exclude lib/openstudio-standards/weather/Weather.stat_file.rb
+--exclude lib/openstudio-standards/utilities/sched_create.rb
+--exclude lib/openstudio-standards/utilities/os_sim_extract.rb
+--exclude lib/openstudio-standards/utilities/hash.rb
+--exclude lib/openstudio-standards/utilities/Add_template_field_to_json.rb
+--exclude lib/openstudio-standards/standards/necb/necb_2011/data/standards_data.rb
 --type-tag ref:"Technical References"
 lib/openstudio-standards/standards/**/*.rb
 lib/openstudio-standards/prototypes/**/*.rb
@@ -12,7 +21,8 @@ docs/Home.md
 docs/UserQuickStartGuide.md
 docs/Features.md
 docs/DeveloperInformation.md
-docs/CodeStructure.md
+docs/RepositoryStructure.md
+docs/CodeArchitecture.md
 docs/AddingAStandard.md
 License.txt
 LGPL-2.1
diff --git a/docs/AddingAStandard.md b/docs/AddingAStandard.md
@@ -1,5 +1,5 @@
-# Adding a Template
-This document gives a high-level overview of adding a new Template (energy code, etc.) to the `openstudio-standards` gem.  If you have questions or get stuck, contact {mailto:[email protected]}.
+# Adding a Standard
+This document gives a high-level overview of adding a new Standard (energy code, etc.) to the `openstudio-standards` gem.  If you have questions or get stuck, contact {mailto:[email protected]}.
 
 ## 1. Setup your development environment
 
@@ -9,7 +9,7 @@ This document gives a high-level overview of adding a new Template (energy code,
 
 1. Open [The OpenStudio_Standards Google Spreadsheet](https://docs.google.com/spreadsheets/d/15-mlZrWbA4srtFHtWRP1dgPeuI5plFdjCb1B79fEukI/edit?usp=sharing)
 2. Request edit privileges by contacting {mailto:[email protected]}
-3. Add your Template to the **Templates** tab.
+3. Add your Standard to the **Templates** tab.
 3. Add your new information to the remaining tabs.
 
 ## 3. TODO - Need to write up instructions
diff --git a/docs/CodeArchitecture.md b/docs/CodeArchitecture.md
@@ -0,0 +1,15 @@
+
+# Code Architecture
+
+In the openstudio-standards library, each code or standard (such as ASHRAE 90.1-2013) is represented by a Class.  Because many different standards share code, instead of having many copies of the same code, code reuse is accomplished through inheritance.
+
+Here is the typical inheritance pattern:
+
+- Standard (_abstract class_)
+  - ASHRAE901 (_abstract class_)
+    - ASHRAE9012004 (_concrete class_)
+    - ASHRAE9012007 (_concrete class_)  
+    - ASHRAE9012010 (_concrete class_)  
+    - ASHRAE9012013 (_concrete class_)  
+
+Methods that are implemented in the **Standard** class are used by the inherited classes such as **ASHRAE90120013**.  However, if **ASHRAE90120013** has special requirements, it can reimplement some or all of the methods found in **Standard**.  These reimplementations can use their own logic.  These reimplementations will only be used by objects of the type **ASHRAE90120013**, they will not be propagated back up to the **Standard** class, or to any other Standards such as **ASHRAE9012004**.
diff --git a/docs/DeveloperInformation.md b/docs/DeveloperInformation.md
@@ -2,42 +2,46 @@
 
 ## Setup
 
-1. Install the [latest version of OpenStudio](https://www.openstudio.net/downloads)
+1. Install the [latest version of OpenStudio](https://www.openstudio.net/downloads). Minimum supported version is 2.4.4.
 2. Install Ruby:
       1. **On Mac**:
-      2. Install Ruby 2.2 using [rbenv](http://octopress.org/docs/setup/rbenv/) (`ruby -v` from command prompt to check installed version).
+      2. Install Ruby 2.2.4 using [rbenv](http://octopress.org/docs/setup/rbenv/) (`ruby -v` from command prompt to check installed version).
       3. **On Windows**:
-      4. Install [Ruby 2.2.6](http://rubyinstaller.org/downloads/) (`ruby -v` from command prompt to check installed version).
-      5. Install [Ruby DevKit](http://rubyinstaller.org/downloads/) by following [these installation instructions](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit)
+      4. Install [Ruby 2.2.4](https://rubyinstaller.org/downloads/archives/) (`ruby -v` from command prompt to check installed version).
+      5. Install [Ruby DevKit](https://rubyinstaller.org/downloads/archives/) by following [these installation instructions](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit)
       6. **Using BTAP development Environment**
       7. Do nothing.
 
 4. Connect Ruby to OpenStudio:
 	1. **On Mac**:
 	2. Create a file called `openstudio.rb`
-	3. Contents: `require "/Applications/openstudio-2.1.0/Ruby/openstudio.rb"` Modify `2.1.0` to the version you installed.
+	3. Contents: `require "/Applications/openstudio-2.6.0/Ruby/openstudio.rb"`. Modify `2.6.0` to the version you installed.
 	4. Save it here: `/usr/lib/ruby/site_ruby/openstudio.rb`
 	5. **On Windows**:
 	6. Create a file called `openstudio.rb`
-	7. Contents: `require "C:/openstudio-2.1.0/Ruby/openstudio.rb"`  Modify `2.1.0` to the version you installed.
+	7. Contents: `require "C:/openstudio-2.6.0/Ruby/openstudio.rb"`.  Modify `2.6.0` to the version you installed.
 	8. Save it here: `C:/Ruby22-x64/lib/ruby/site_ruby/openstudio.rb`
 	9. Start > right click Computer > Properties > Advanced system settings > Environment variables.  In the User variables section (top) add a new Variable with the name `GEM_PATH` and the Value `C:\Ruby22-x64\lib\ruby\gems\2.2.0`.
 	10. **Using BTAP development Environment**
 	11.  Do nothing.
 
+5. Enable your OpenStudio Application installation to use the version of the gem built through the development process 
+    1. **On Windows**:
+    2. Start > right click Computer > Properties > Advanced system settings > Environment variables.
+    3. In the User variables section (top) add a new Variable with the name `GEM_HOME` and the Value `C:\Ruby22-x64\lib\ruby\gems\2.2.0`.
+
 5. Install the `bundler` ruby gem. (`gem install bundler` from command prompt)
 6. Install the `json` ruby gem. (`gem install json` from command prompt)
 7. Install [Git](https://git-scm.com/).
 8. Install [GitHub desktop](https://desktop.github.com/) or another GUI that makes Git easier to use.
 8. Clone the [source code](https://github.com/NREL/openstudio-standards.git) using GitHub desktop (easier) or Git (harder).
-9. Run all commands below from the `/openstudio-standards/openstudio-standards` directory 
+9. Run all commands below from the top level directory 
 10. **On Windows**, use the Git Bash instead of the default command prompt.
 11. **On Mac** the default terminal is fine.
 12. **Using BTAP development Environment** use the terminator terminal ideally.
-11. Navigate to the `openstudio-standards` directory.
-12. Command prompt: `bundle install`. This will install all ruby gems necessary to develop this code.
-13. Sign up for an account at [CircleCI](https://circleci.com/) and follow the `NREL/openstudio-standards` project.
-14. That's it, you are ready to make changes!
+13. Command prompt: `bundle install`. This will install all ruby gems necessary to develop this code.
+14. Sign up for an account at [CircleCI](https://circleci.com/) and follow the `NREL/openstudio-standards` project.
+15. That's it, you are ready to make changes!
 
 ## Development Process
 
@@ -53,40 +57,41 @@
 
 This project uses [Rake](http://rake.rubyforge.org/) to run tasks from the terminal.  
 
-`rake -T`: List all available commands
-
-- `rake build`                    # Build openstudio-standards-0.1.15.gem into the pkg directory
-- `rake clean`                    # Remove any temporary products
-- `rake clobber`                  # Remove any generated files
-- `rake data:update`              # Download OpenStudio_Standards from Google & export JSONs
-- `rake data:update:costing`      # Update RS-Means Database
-- `rake data:update:manual`       # Export JSONs from OpenStudio_Standards
-- `rake doc`                      # Generate the documentation
-- `rake doc:show`                 # Show the documentation in a web browser
-- `rake install`                  # Build and install openstudio-standards-0.1.15.gem into system gems
-- `rake install:local`            # Build and install openstudio-standards-0.1.15.gem into system gems without network access
-- `rake release[remote`]          # Create tag v0.1.15 and build and push openstudio-standards-0.1.15.gem to Rubygems
-- `rake rubocop`                  # Check the code for style consistency
-- `rake rubocop:auto_correct`     # Auto-correct RuboCop offenses
-- `rake rubocop:show`             # Show the rubocop output in a web browser
-- `rake test:btap_json_test`      # Run tests for btap_json_test
-- `rake test:circ-90_1_general`   # Run tests for circ-90_1_general
-- `rake test:circ-90_1_prm`       # Run tests for circ-90_1_prm
-- `rake test:circ-all-tests`      # Run tests for circ-all-tests
-- `rake test:circ-doe_prototype`  # Run tests for circ-doe_prototype
-- `rake test:circ-necb`           # Run tests for circ-necb
-- `rake test:circ-necb_bldg`      # Run tests for circ-necb_bldg
-
+`bundle exec rake -T`: List all available commands
+
+- `bundle exec rake build`                    # Build openstudio-standards-X.X.XX.gem into the pkg directory
+- `bundle exec rake clean`                    # Remove any temporary products
+- `bundle exec rake clobber`                  # Remove any generated files
+- `bundle exec rake data:update`              # Download OpenStudio_Standards from Google & export JSONs
+- `bundle exec rake data:update:costing`      # Update RS-Means Database
+- `bundle exec rake data:update:manual`       # Export JSONs from OpenStudio_Standards
+- `bundle exec rake doc`                      # Generate the documentation
+- `bundle exec rake doc:show`                 # Show the documentation in a web browser
+- `bundle exec rake install`                  # Build and install openstudio-standards-X.X.XX.gem into system gems
+- `bundle exec rake install:local`            # Build and install openstudio-standards-X.X.XX.gem into system gems without network access
+- `bundle exec rake library:export`           # Export libraries for the OpenStudio Application
+- `bundle exec rake release[remote`]          # Create tag vX.X.XX and build and push openstudio-standards-X.X.XX.gem to Rubygems
+- `bundle exec rake rubocop`                  # Check the code for style consistency
+- `bundle exec rake rubocop:auto_correct`     # Auto-correct RuboCop offenses
+- `bundle exec rake rubocop:show`             # Show the rubocop output in a web browser
+- `bundle exec rake test:btap_json_test`      # Run tests for btap_json_test
+- `bundle exec rake test:circ-90_1_general`   # Run tests for circ-90_1_general
+- `bundle exec rake test:circ-90_1_prm`       # Run tests for circ-90_1_prm
+- `bundle exec rake test:circ-all-tests`      # Run tests for circ-all-tests
+- `bundle exec rake test:circ-doe_prototype`  # Run tests for circ-doe_prototype
+- `bundle exec rake test:circ-necb`           # Run tests for circ-necb
+- `bundle exec rake test:circ-necb_bldg`      # Run tests for circ-necb_bldg
+- `bundle exec rake test:necb_local_bldgs_regression_tests`  # Run tests for necb_local_bld...`
 
 ### Modify the code
 
-As you add to/modify the code, please try to fit changes into the current structure rather than bolting things on willy-nilly.  See the {file:docs/CodeStructure.md Code Structure page} to see how the code is organized.  If you don't understand something or want to discuss your plan before you get started, contact <mailto:[email protected]>.
+As you add to/modify the code, please try to fit changes into the current structure rather than bolting things on willy-nilly.  See the {file:docs/RepositoryStructure.md Repository Structure page} to see how the code is organized.  If you don't understand something or want to discuss your plan before you get started, contact <mailto:[email protected]>.
 
 1. Make a new branch for your changes.
 2. Modify the code on your branch.
 3. Modify the [OpenStudio_Standards Google Spreadsheet](https://docs.google.com/spreadsheets/d/15-mlZrWbA4srtFHtWRP1dgPeuI5plFdjCb1B79fEukI/edit?usp=sharing)
  - To get edit access to this spreadsheet, contact <mailto:[email protected]>.
-4. `rake data:update` to download the latest version of the spreadsheet from Google Drive and export the JSON files.
+4. `bundle exec rake data:update` to download the latest version of the spreadsheet from Google Drive and export the JSON files.
 
 ### Test the code
 
@@ -102,8 +107,8 @@ Tests prove that your code works as expected, but more importantly they help mak
 Good documentation is critical.  Changes or additions without good documentation will not be accepted.  This library uses [YARD](http://yardoc.org/) to generate documentation.  You simply write the documentation inline as specially tagged comments and the rest happens automagically.  This [YARD cheat sheet](https://gist.github.com/chetan/1827484#methods) quickly shows you how to document things.  You can also look at the other methods documented in the code.
 
 1. Make sure your methods are documented.
-2. `rake doc` Generate the documentation and document any undocumented methods that are listed
-3. `rake doc:show` Inspect the documentation in a browser to make sure it looks right.
+2. `bundle exec rake doc` Generate the documentation and document any undocumented methods that are listed
+3. `bundle exec rake doc:show` Inspect the documentation in a browser to make sure it looks right.
 
 ### Push branch to GitHub