Skip to content

Commit

Permalink
Merge pull request #1824 from NREL/update_documentation
Browse files Browse the repository at this point in the history 
Update markdown documentation
  • Loading branch information
@mdahlhausen
mdahlhausen authored Oct 8, 2024
2 parents 9b73867 + e9bed15 commit ebad829
Show file tree
Hide file tree
Showing 16 changed files with 143 additions and 271 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If you are a user, see the [User Quick Start Guide](docs/UserQuickStartGuide.md)

## Online Documentation

If you are a user, please see the [Online Documentation](http://www.rubydoc.info/gems/openstudio-standards) for an overview of how the library is structured and how it is used.
If you are a user, please see the [Online Documentation](https://gemdocs.org/gems/openstudio-standards) for an overview of how the library is structured and how it is used.

## Developer Information

Expand Down
23 changes: 20 additions & 3 deletions docs/CodeArchitecture.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,32 @@

# Code Architecture

## Modules
The openstudio-standards library contains a library of generic methods to create, modify, or get information about an OpenStudio model. These are organized in modules. See the ruby documentation for a detailed method list.
- constructions
- create_typical
- daylighting
- geometry
- hvac
- infiltration
- qaqc
- schedules
- service_water_heating
- space
- standards (see below)
- thermal_zone
- weather

## Standards
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_)
- 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**.
119 changes: 49 additions & 70 deletions docs/DeveloperInformation.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,62 @@
# Developer Information

## Setup

1. Install the [latest version of OpenStudio](https://www.openstudio.net/downloads). We recommend a minimum version of OpenStudio 3.2.1.
2. Install the Ruby version that corresponds to your OpenStudio install. See the [OpenStudio SDK Version Compatibility Matrix](https://github.com/NREL/OpenStudio/wiki/OpenStudio-SDK-Version-Compatibility-Matrix).
1. **On Mac**:
2. Install Ruby 2.7.2 using [rbenv](http://octopress.org/docs/setup/rbenv/) (`ruby -v` from command prompt to check installed version).
3. **On Windows**:
4. Install [Ruby+Devkit 2.7.2](https://rubyinstaller.org/downloads/archives) (`ruby -v` from command prompt to check installed version).
5. **Using BTAP development Environment**
6. Do nothing.

4. Connect Ruby to OpenStudio:
1. **On Mac**:
2. Create a file called `openstudio.rb`
3. Contents: `require "/Applications/openstudio-3.2.1/Ruby/openstudio.rb"`. Modify `3.2.1` 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-3.2.1/Ruby/openstudio.rb"`. Modify `3.2.1` to the version you installed.
8. Save it here: `C:/Ruby27-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:\Ruby27-x64\lib\ruby\gems\2.5.0`.
10. **Using BTAP development Environment**
11. Do nothing.

5. Install the `bundler` ruby gem. (`gem install bundler` from command prompt)
6. Install [Git](https://git-scm.com/).
7. 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 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.
13. Command prompt: `bundle install`. This will install all ruby gems necessary to develop this code.
14. That's it, you are ready to make changes!
1. Install the [latest version of OpenStudio](https://www.openstudio.net/downloads). We recommend a minimum version of OpenStudio 3.7.0.
2. Install the Ruby version that corresponds to your OpenStudio install. See the [OpenStudio SDK Version Compatibility Matrix](https://github.com/NREL/OpenStudio/wiki/OpenStudio-SDK-Version-Compatibility-Matrix) of the correct version. OpenStudio versions 3.2.0 through 3.7.0 use Ruby 2.7.2, OpenStudio 3.8.0 and above uses Ruby 3.2.2.
- **On Mac**: Install Ruby 2.7.2 using [rbenv](http://octopress.org/docs/setup/rbenv/)
- **On Windows**: Install [Ruby+Devkit 2.7.2](https://rubyinstaller.org/downloads/archives)
- **On Linux**: Use [rbenv](http://octopress.org/docs/setup/rbenv/) or your package manger to install ruby
- **Using BTAP development Environment**: Do nothing.
- Call `ruby -v` from command prompt to check installed version.
3. Connect Ruby to OpenStudio:
- **On Mac**:
1. Create a file called `openstudio.rb`
2. Contents: `require "/Applications/openstudio-3.7.0/Ruby/openstudio.rb"`. Modify `3.7.0` to the OpenStudio version you installed.
3. Save it here: `/usr/lib/ruby/site_ruby/openstudio.rb`
- **On Windows**:
1. Create a file called `openstudio.rb`
2. Contents: `require "C:/openstudio-3.7.0/Ruby/openstudio.rb"`. Modify `3.7.0` to the OpenStudio version you installed.
3. Save it here: `C:/Ruby27-x64/lib/ruby/site_ruby/openstudio.rb`. Modify `Ruby27-x64` to the Ruby version you installed.
4. 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:\Ruby27-x64\lib\ruby\gems\2.5.0`. Modify `Ruby27-x64` to the Ruby version you installed.
- **On Linux**:
1. Create a file called `openstudio.rb`
2. Contents: `require "/usr/local/openstudio-3.7.0/Ruby/openstudio.rb"`. Modify `3.7.0` to the OpenStudio version you installed.
3. Save it here: `/usr/local/lib/ruby/site_ruby/openstudio.rb`.
- If you are having trouble locating the paths in your specific linux setup, you can find the ruby version with `gem environment` in command prompt and the location of openstudio with `which openstudio`.
- **Using BTAP development Environment**:
1. Do nothing.
4. Install [Git](https://git-scm.com/).
5. Install [GitHub desktop](https://desktop.github.com/) or another GUI that makes Git easier to use.
6. Clone the [source code](https://github.com/NREL/openstudio-standards.git) using GitHub desktop (easier) or Git (harder).
7. Install the `bundler` ruby gem. (`gem install bundler` from command prompt)
8. Run `bundle install` in command prompt from the top level `openstudio-standards` directory. This will install the correct ruby gem versions necessary for development.

## Development Process

### Summary

1. Modify the code
2. Test the code (new code plus old code to make sure you didn't break anything)
3. Document the code
5. Push branch to GitHub repository
6. Continuous automation runs tests
7. Pull request
8. Code review and merge
8. Code review and merge

This project uses [Rake](http://rake.rubyforge.org/) to run tasks from the terminal.
This project uses [Rake](http://rake.rubyforge.org/) to run tasks from the terminal.

`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:apicheck` # Check Google Drive configuration
- `bundle exec rake data:download` # Download OpenStudio_Standards spreadsheets from Google Drive
- `bundle exec rake data:update` # Download OpenStudio_Standards from Google & export JSONs
- `bundle exec rake data:update` # Download OpenStudio_Standards spreadsheets and generate JSONs
- `bundle exec rake data:update:manual` # Generate JSONs from OpenStudio_Standards spreadsheets
- `bundle exec rake data:export:jsons` # Export JSONs from OpenStudio_Standards to data library
- `bundle exec rake data:update:costing` # Update RS-Means Database
- `bundle exec rake doc` # Generate the documentation
- `bundle exec rake doc:show` # Show the documentation in a web browser
- `bundle exec rake doc:show` # Generate the documentation and show 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 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
Expand All @@ -78,59 +68,48 @@ This project uses [Rake](http://rake.rubyforge.org/) to run tasks from the termi
- `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/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]>.

### Modify the code
As you add to/modify the code, please follow the code architecture. 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. If you have data, modify the .json files and run commands to update the database, as appropriate. Historically, openstudio-standards data used a series of google spreadsheets, and is still used for non-90.1- standards. See [OpenStudio_Standards Google Spreadsheet](https://drive.google.com/drive/folders/1x7yEU4jnKw-gskLBih8IopStwl0KAMEi?usp=sharing). Contact <mailto:[email protected]> for access.
4. You may edit the spreadsheet or modify a copy of the data, then download the spreadsheet to the `data/standards` directory, and run `bundle exec rake data:update:manual` to update the JSONs.
5. If you have edit access to the spreadsheets, you can use `bundle exec rake data:update` to download the latest version of the spreadsheet from Google Drive and export the JSON files.

### Test the code

Tests prove that your code works as expected, but more importantly they help make sure that changes don't break other code. If your code doesn't have tests and someone else makes changes that break it, it's your own fault.
### Modify the data
1. 90.1 standards data is available in [this database](https://github.com/pnnl/building-energy-standards-data). All 90.1 changes happen on that database. Data for other standards or templates lives in the .json files in openstudio-standards.
2. If you have data, modify the .json files and run commands to update the database, as appropriate. Historically, openstudio-standards data used a series of google spreadsheets, and is still used for non-90.1-standards. See [OpenStudio_Standards Google Spreadsheet](https://drive.google.com/drive/folders/1x7yEU4jnKw-gskLBih8IopStwl0KAMEi?usp=sharing). Contact <mailto:[email protected]> for access.
3. You may edit the spreadsheet or modify a copy of the data, then download the spreadsheet to the `data/standards` directory, and run `bundle exec rake data:update:manual` to update the JSONs.

### Test the code
Tests prove that your code works as expected, but more importantly they help make sure that changes don't break other code. If your code doesn't have tests and someone else makes changes that break it, it's your own fault.
1. Create a new file called `test_XX.rb` in the `/test/subdirectory` directory.
2. Put tests into your file. See other test files for examples.
2. `ruby test/sub_directory/test_XX.rb` Run your new test file.
2. Put tests into your file. See other test files for examples.
2. Call `ruby test/sub_directory/test_XX.rb` to run your new test file.
3. Fix your code and make sure your tests pass.

### Document the code

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.
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. 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. `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

### Push branch to GitHub
1. Commit your changes to your branch.
2. Merge /Master into your branch and resolve any conflicts.
3. Push your branch to GitHub.

### Pull request

Once your code is done and the tests are passing locally on your branch with Master merged in, go to GitHub and create a Pull Request. This tells the main developers that you have changes to bring into the main code.
Once your code is done and the tests are passing locally on your branch with Master merged in, go to GitHub and create a Pull Request. This tells the main developers that you have changes to bring into the main code. They will review and suggest edits or merge.

### Code Review & Merge

The main developers will review your changes and either approve the pull request or give you some comments. If they approve the pull request, you are done and your changes are now part of the main code!

### Look at the continuous integration results

1. When a commit is made to any branch, the continuous integration machine will run all the tests.
2. For pull requests, the status of the tests will automatically be posted to GitHub.
3. Developers will need to be given access to the continuous integration system to see detailed results.

## Issues and New Features

1. Issues and feature requests are reported on the [GitHub Repository Issues Page](https://github.com/NREL/openstudio-standards/issues ).
2. Issues should be labeled according to the [OpenStudio Issue Prioritization Guide](https://github.com/NREL/OpenStudio/wiki/Issue-Prioritization)
3. Failing tests do not need to be listed as issues; they should be fixed if they fail.

## Data
A database containing all the data used by openstudio-standards (and more) is being developed [here](https://github.com/pnnl/building-energy-standards-data)
- Issues and feature requests are reported on the [GitHub Repository Issues Page](https://github.com/NREL/openstudio-standards/issues).
- Issues should be labeled according to the [OpenStudio Issue Prioritization Guide](https://github.com/NREL/OpenStudio/wiki/Issue-Prioritization).
- Failing tests do not need to be listed as issues; they should be fixed if they fail.
Loading

0 comments on commit ebad829

Please sign in to comment.