Merge pull request #176 from BuildingSync/task/small-fixes

Updated Onboarding & Collaborators

Author: axelstudios

README.md

@@ -7,55 +7,54 @@ This is the repository for the BuildingSync Validator web application.
 ## Installation
 
 1. Clone the repository.
-1. Setup python 3.  You can use a virtual environment:
+1. Setup python 3. You can use a virtual environment:
     ```bash
     pyenv install 3.6.5
     pyenv virtualenv 3.6.5 bsync-validator-3.6.5
     pyenv local bsync-validator-3.6.5
     ```
 1. Install PostgreSQL server for local development (if desired)
-	* Once installed, create your local database and user:
-		```bash
-		psql -c 'DROP DATABASE bsync_validator;'
-		psql -c 'CREATE DATABASE bsync_validator;'
-		psql -c "CREATE USER bsync_validator WITH ENCRYPTED PASSWORD 'bsync_validator';"
-		psql -c 'GRANT ALL PRIVILEGES ON DATABASE bsync_validator TO bsync_validator;'
-		psql -c 'ALTER USER bsync_validator CREATEDB;'
-		```
+    * Once installed, create your local database and user:
+        ```bash
+        psql -c 'DROP DATABASE bsync_validator;'
+        psql -c 'CREATE DATABASE bsync_validator;'
+        psql -c "CREATE USER bsync_validator WITH ENCRYPTED PASSWORD 'bsync_validator';"
+        psql -c 'GRANT ALL PRIVILEGES ON DATABASE bsync_validator TO bsync_validator;'
+        psql -c 'ALTER USER bsync_validator CREATEDB;'
+        ```
 1. Install Django and associated requirements:
-	```bash
-	pip install -r requirements.txt
-	```
-1.  Initialize the database:
-	```bash
-	python manage.py migrate
-	```
-1.  Create a superuser:
-	```bash
-	python manage.py createsuperuser
-	```
+    ```bash
+    pip install -r requirements.txt
+    ```
+1. Initialize the database:
+    ```bash
+    python manage.py migrate
+    ```
+1. Create a superuser:
+    ```bash
+    python manage.py createsuperuser
+    ```
 1. Start the app:
-	```bash
-	python manage.py runserver
-	```
-
+    ```bash
+    python manage.py runserver
+    ```
 
 ## Local Development
 
 * When making changes to models, run the following command to make migrations:
-	```bash
-	python manage.py makemigrations
-	python manage.py migrate
-	```
+    ```bash
+    python manage.py makemigrations
+    python manage.py migrate
+    ```
 
 * To test schema import, you can run this command:
-	```bash
-	python manage.py reset_schema --schema_version=1.0.0
-	```
+    ```bash
+    python manage.py reset_schema --schema_version=1.0.0
+    ```
 
-**NOTE**: You will need to be off the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbxml schema cannot be imported when on the NREL VPN.
+**NOTE**: You will need to be _off_ the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbXML schema cannot be imported when on the NREL VPN.
 
-### Precommit
+### Pre-commit
 
 This project used `pre-commit <https://pre-commit.com/>`_ to ensure code consistency. To enable pre-commit, run the following from the command line.
 
@@ -73,9 +72,9 @@ pre-commit run --all-files
 ### Testing
 
 * To run test:
-   ```bash
-   ./manage.py test
-   ```
+    ```bash
+    ./manage.py test
+    ```
 
 * To calculate coverage:
     ```bash
@@ -85,7 +84,7 @@ pre-commit run --all-files
 
 ### Pep
 
-* Run the following command to clean-up your code before committing:
+* Run the following command to clean up your code before committing:
 ```bash
 autopep8 --in-place --aggressive --aggressive --recursive --max-line-length 100 --ignore E501,E402,W503,E731 --exclude=conf.py,structure.py .
 
@@ -96,26 +95,26 @@ tox -e flake8
 
 ### BuildingSync Schema
 
-The BuildingSync Schema Viewer can support multiple versions of the BuildingSync schema.  Admin users can manage schemas from the Django Administration console.  Click on the 'Admin' link in the top navigation bar to access the Django Administration pages.
+The BuildingSync Schema Viewer can support multiple versions of the BuildingSync schema. Admin users can manage schemas from the Django Administration console. Click on the 'Admin' link in the top navigation bar to access the Django Administration pages.
 
-To add a schema, specify the name, version, and schema file (XSD) to parse and save the record.  The schema file will be parsed automatically.  **NOTE**: You will need to be off the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbxml schema cannot be imported when on the NREL VPN.
+To add a schema, specify the name, version, and schema file (XSD) to parse and save the record. The schema file will be parsed automatically. **NOTE**: You will need to be _off_ the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbXML schema cannot be imported when on the NREL VPN.
 
-To modify an existing schema, click on the edit link.  If changes are made to the uploaded XSD schema file and re-uploaded, ensure that the 'schema parsed' checkbox is unchecked before saving the record.  This will trigger the automatic schema parsing.
+To modify an existing schema, click on the edit link. If changes are made to the uploaded XSD schema file and re-uploaded, ensure that the 'schema parsed' checkbox is unchecked before saving the record. This will trigger the automatic schema parsing.
 
 ### Use Cases
 
-Authenticated users can add private use cases to the BuildingSync Schema Viewer.  Use cases are represented by a schematron file that defines a set of rules and patterns.
+Authenticated users can add private use cases to the BuildingSync Schema Viewer. Use cases are represented by a schematron file that defines a set of rules and patterns.
 
 To add a use case, click on the 'Use Case' link in the top navigation bar, then click on the '+ New Use Case' button.
-Select a name and a BuildingSync schema version.  Select your use case definitions schematron file and upload, then click 'Submit'.
+Select a name and a BuildingSync schema version. Select your use case definitions schematron file and upload, then click 'Submit'.
 
 Once ready, contact a BuildingSync admin to make the use case public. Public use cases will be available on the 'Validator' page to validate XML files submitted by users.
 
-Admin users: Find the use case in the Django Administration console and click the edit button.  Check the 'Make public' checkbox and save.
+Admin users: Find the use case in the Django Administration console and click the edit button. Check the 'Make public' checkbox and save.
 
 ### Validator
 
-The validator page allows users to validate XMLs against the BuildingSync schema and its public use cases.  It can be tried with selected example files, or custom XML files can be uploaded for validation.
+The validator page allows users to validate XMLs against the BuildingSync schema and its public use cases. It can be tried with selected example files, or custom XML files can be uploaded for validation.
 
 #### Validator API
 
@@ -124,7 +123,7 @@ There is also a validator endpoint to validate XML files against the BuildingSyn
 #### SINGLE XML
 
 Request: POST to https://buildingsync.net/api/validate
-Use form-data to specify the following parameters for schema version and XML file:  ```schema_version``` and ```file```.
+Use form-data to specify the following parameters for schema version and XML file: `schema_version` and `file`.
 
 Example Response:
 ```json
@@ -165,7 +164,7 @@ Example Response:
 #### ZIP with multiple XMLs
 
 Request: POST to https://buildingsync.net/api/validate
-Use form-data to specify the following parameters for schema version and XML file:  ```schema_version``` and ```file```.
+Use form-data to specify the following parameters for schema version and XML file: `schema_version` and `file`.
 
 Example Response:
 ```json
@@ -236,25 +235,24 @@ Example Response:
 }
 ```
 
-
 ### BEDES
 
 BEDES parsing and mapping to the BuildingSync schema is not an automated process, due to the manual inspections/corrections required.
 
 To parse and map a new BEDES version:
 
-1. Download the ```bedes_online_dictionary_uuid-lo.xml``` and the ```bedes_online_dictionary_uuid-terms.xml``` files from the BEDES website.
+1. Download the bedes_online_dictionary_uuid-lo.xml` and the `bedes_online_dictionary_uuid-terms.xml` files from the BEDES website.
 
-1. Place these new BEDES XMLs in the lib/bedes/vX.X directory.  vX.X refers to the BEDES version here.
+1. Place these new BEDES XMLs in the lib/bedes/vX.X directory. vX.X refers to the BEDES version here.
 
 1. Parse the BEDES XMLs into a JSON file and map the BEDES terms to the BuildingSync attributes:
     ```bash
     python manage.py bedes --schema_version=X.X.X --bedes_version=X.X
     ```
     Note that the bedes_version contains a v, ex: v2.2.
-    This will create a ```bedes_vX.X.json``` file in the lib/bedes/vX.X directory.  It will also create 2 CSV files:  ```bedes-mappings-enumerations.csv``` and ```bedes-mappings-terms.csv``` in the lib/bedes/vX.X/schemaX.X directory.
+    This will create a bedes_vX.X.json` file in the lib/bedes/vX.X directory. It will also create 2 CSV files: `bedes-mappings-enumerations.csv` and `bedes-mappings-terms.csv` in the lib/bedes/vX.X/schemaX.X directory.
 
-    *Note* &mdash; The BEDES terms must be mapped for each version of the BuildingSync schema by calling the ```python manage.py bedes``` command above.
+    _Note_ &mdash; The BEDES terms must be mapped for each version of the BuildingSync schema by calling the python manage.py bedes` command above.
 
 1. Review these mapping files and make changes as needed.
 
@@ -273,8 +271,8 @@ Admin interface is available at `/admin`
 
 Follow these steps to add a new schema version to the selection tool:
 
-1. Add the schema file in the admin interface.  Must have admin privileges.  The schema will get automatically parsed.
-1. Convert existing use cases schematron files to the new schema.  Add the new use cases.
+1. Add the schema file in the admin interface. Must have admin privileges. The schema will get automatically parsed.
+1. Convert existing use cases schematron files to the new schema. Add the new use cases.
 1. When the use cases have been reviewed, make them public in the admin interface.
 1. Create XML example files and place them in the `lib/validator/examples/schema<VERSION>` directory.
 1. Test the validator with the new XML example files.
@@ -287,14 +285,14 @@ Follow these steps to add new example tables from the TestSuite repo
 1. Clone the [TestSuite](https://github.com/BuildingSync/TestSuite) repo
 2. Install [pandoc](https://pandoc.org/installing.html)
 3. Convert the TestSuite README to html:
-    ``` pandoc README.md -s -o README.html ```
-4. Copy the tables part of the README.html and paste to replace the old content in ```bsyncviewer/templates/examples.html```.
+    `pandoc README.md -s -o README.html`
+4. Copy the tables part of the README.html and paste to replace the old content in `bsyncviewer/templates/examples.html`.
 
 ### Adding an OpenStudio Simulation Use Case from the TestSuite repo
 
-1. The relevant files are currently on the `develop` branch of the [TestSuite](https://github.com/BuildingSync/TestSuite/tree/develop) repo.  Clone the repo locally.
-1. OpenStudio Simulation use case schematron files include patterns from a [library of schematron files](https://github.com/BuildingSync/TestSuite/tree/develop/lib).  Copy these files from the TestSuite repo into the selection-tool at the following location: ```bsyncviewer/testsuitelib```.
-1. Open the relevant use case file from the TestSuite repo.  For example: [L00_OpenStudio_Simulation.sch](https://github.com/BuildingSync/TestSuite/blob/develop/schematron/v2.2.0/v2-2-0_L000_OpenStudio_Simulation.sch).  Edit the include statements at the top of the file with relative paths to the buildingsync-website testsuitelib directory.  Save the file.
+1. The relevant files are currently on the `develop` branch of the [TestSuite](https://github.com/BuildingSync/TestSuite/tree/develop) repo. Clone the repo locally.
+1. OpenStudio Simulation use case schematron files include patterns from a [library of schematron files](https://github.com/BuildingSync/TestSuite/tree/develop/lib). Copy these files from the TestSuite repo into the selection-tool at the following location: `bsyncviewer/testsuitelib`.
+1. Open the relevant use case file from the TestSuite repo. For example: [L00_OpenStudio_Simulation.sch](https://github.com/BuildingSync/TestSuite/blob/develop/schematron/v2.2.0/v2-2-0_L000_OpenStudio_Simulation.sch). Edit the include statements at the top of the file with relative paths to the buildingsync-website testsuitelib directory. Save the file.
     ```bash
       <include href="../../testsuitelib/rootElements.sch#root.oneOfEachUntilBuilding"/>
       <include href="../../testsuitelib/rootElements.sch#root.oneOfEachFacilityUntilScenario"/>
@@ -305,10 +303,10 @@ Follow these steps to add new example tables from the TestSuite repo
       <include href="../../testsuitelib/floorElements.sch#fa.oneOfType"/>
       <include href="../../testsuitelib/floorElements.sch#fa.haveTypeAndValue"/>
     ```
-1. Add the use case to the selection-tool by browsing to the ```/use_cases``` URL and clicking the *New Use Case* button.
+1. Add the use case to the selection-tool by browsing to the `/use_cases` URL and clicking the _New Use Case_ button.
     1. Fill out the name, description, and schema version
     1. Upload the file that was modified in the previous step
     1. Save
 1. Make the use case public from the selection-tool admin interface.
-1. If you have any example files to add to the selection-tool (for example, for the L000 OpenStudio Simulation use case, there are [2 examples files](https://github.com/BuildingSync/TestSuite/tree/develop/spec/use_cases/schema2.0.0/examples)), add them in the appropriate schema directory in ```bsyncviewer/lib/validator/examples```. Regenerate the ```example_files.zip``` archive.  This will make the files available as examples at the ```/validator``` URL.
+1. If you have any example files to add to the selection-tool (for example, for the L000 OpenStudio Simulation use case, there are [2 examples files](https://github.com/BuildingSync/TestSuite/tree/develop/spec/use_cases/schema2.0.0/examples)), add them in the appropriate schema directory in `bsyncviewer/lib/validator/examples`. Regenerate the `example_files.zip` archive. This will make the files available as examples at the `/validator` URL.
 1. You can now validate XMLs against the new use case.

bsyncviewer/management/commands/generate_onboarding.py

@@ -0,0 +1,14 @@
+import os
+import subprocess
+
+from django.core.management.base import BaseCommand
+
+
+class Command(BaseCommand):
+    help = 'Generate onboarding html and pdf'
+
+    def handle(self, *args, **options):
+        subprocess.check_output('pandoc --wrap=none ../../docs/onboarding.md -o onboarding_content.html',
+                                cwd='bsyncviewer/templates').decode()
+        subprocess.check_output('pandoc ../../docs/onboarding.md -o documents/BuildingSync-on-boarding.pdf',
+                                cwd='bsyncviewer/static').decode()

bsyncviewer/static/documents/BuildingSync-on-boarding.pdf

@@ -110,7 +110,7 @@ <h6>Leverage expert support from DOE and the National Renewable Energy Laborator
       </div>
     </section>
 
-    <p>Get started by downloading the <a href="https://github.com/BuildingSync/schema/releases" target="_blank" rel="noopener">BuildingSync schema</a> or
+    <p>Get started by downloading the <a href="https://github.com/BuildingSync/schema/releases/latest" target="_blank" rel="noopener">BuildingSync schema</a> or
       <a href="https://buildingsync.net/validator" target="_blank" rel="noopener">validating</a> your use case.</p>
   </div>
 

bsyncviewer/static/images/buildingsync-logo.png

@@ -13,19 +13,19 @@
           <div class="serv-row text-center">
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://www.pnnl.gov/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/pnnl.png' %}" alt="PNNL logo"></a>
+                <a href="https://www.erdc.usace.army.mil/Locations/CERL/" target="_blank" rel="noopener"><img class="collab-image-sf" src="{% static 'images/cerl.png' %}" alt="CERL logo"></a>
               </div>
             </div>
 
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://psdconsulting.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/psd.png' %}" alt="PSD logo"></a>
+                <a href="https://doee.dc.gov/" target="_blank" rel="noopener"><img class="collab-image-sf" src="{% static 'images/doee.jpg' %}" alt="DOEE logo"></a>
               </div>
             </div>
 
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://buildee.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/buildee.png' %}" alt="Buildee logo"></a>
+                <a href="https://openstudio.net/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/openstudio.png' %}" alt="OpenStudio logo"></a>
               </div>
             </div>
           </div>
@@ -35,43 +35,35 @@
           <div class="serv-row text-center">
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://www.brightpower.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/bright_power.png' %}" alt="Bright Power logo"></a>
+                <a href="https://www.pnnl.gov/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/pnnl.png' %}" alt="PNNL logo"></a>
               </div>
             </div>
 
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://aecom.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/aecom.png' %}" alt="AECOM logo"></a>
+                <a href="https://psdconsulting.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/psd.png' %}" alt="PSD logo"></a>
               </div>
             </div>
 
             <div class="col-md-4">
-              <div class="serv-item">
-                <a href="https://brandnewbox.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/brand_new_box.png' %}" alt="Brand New Box logo"></a>
+              <div class="serv-item-sf">
+                <a href="https://sfenvironment.org/" target="_blank" rel="noopener"><img class="collab-image-sf" src="{% static 'images/sf_environment.png' %}" alt="SF Environment logo"></a>
               </div>
             </div>
           </div>
         </div>
 
         <div class="row">
           <div class="serv-row text-center">
-            <div class="col-md-4">
-              <div class="serv-item">
-                <a href="https://www.lbl.gov/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/berkley_lab_logo.svg' %}" alt="LBL logo"></a>
-              </div>
-            </div>
-
-            <div class="col-md-4">
-              <div class="serv-item-sf">
-                <a href="https://sfenvironment.org/" target="_blank" rel="noopener"><img class="collab-image-sf" src="{% static 'images/sf_environment.png' %}" alt="SF Environment logo"></a>
-              </div>
-            </div>
+            <div class="col-md-4"></div>
 
             <div class="col-md-4">
               <div class="serv-item">
-                <a href="https://audette.io/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/audette-logo.png' %}" alt="Audette logo"></a>
+                <a href="https://buildee.com/" target="_blank" rel="noopener"><img class="collab-image" src="{% static 'images/buildee.png' %}" alt="Buildee logo"></a>
               </div>
             </div>
+
+            <div class="col-md-4"></div>
           </div>
         </div>
       </div>