Merge pull request #280 from jgunstone/272-build-gh-pages

272 build gh pages

.github/workflows/build-docs.yml

@@ -0,0 +1,41 @@
+name: Build docs
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: GitHub Tag Name example
+        run: |
+          echo "Status: *release* $GITHUB_REF_NAME" > release.md
+          
+      - name: Setup Mambaforge
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+            miniforge-variant: Mambaforge
+            miniforge-version: latest
+            activate-environment: bdns
+            use-mamba: true
+
+      - name: Create environment
+        run: mamba env update -n bdns -f environment.yml
+
+      - name: Install tinytex
+        shell: bash -l {0}
+        run: quarto install tinytex
+
+      - name: Build docs
+        shell: bash -l {0}
+        run: quarto render .
+
+      - name: Push docs to gh-pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: _site

.gitignore

@@ -1,2 +1,5 @@
 .vscode
 .idea
+
+/.quarto/
+/_site/*

BDNS_Abbreviations_Register.csv

@@ -2,10 +2,10 @@ asset_description,asset_abbreviation,dbo_entity_type,ifc_class,ifc_type,can_be_c
 access control - RFID controller,RFIDC,,IfcController,NOTDEFINED,1
 access control - RFID reader,RFIDR,,IfcCommunicationsAppliance,SCANNER,1
 access control - access control system,ACS,,IfcDistributionSystem,SECURITY,1
+access control - audio intercom,AIC,,IfcSwitchingDevice,NOTDEFINED,1
 access control - biometric reader,BIOR,,IfcCommunicationsAppliance,SCANNER,1
 access control - request to exit,RTE,,IfcSwitchingDevice,CONTACTOR,1
 access control - video intercom,VIC,,IfcSwitchingDevice,NOTDEFINED,1
-access control - audio intercom,AIC,,IfcSwitchingDevice,NOTDEFINED,1
 actuator,ACT,,IfcActuator,NOTDEFINED,1
 actuator - frost protection switch,FPSW,,IfcActuator,ELECTRICACTUATOR,1
 actuator - motorized window operator,WDO,,IfcActuator,ELECTRICACTUATOR,1
@@ -65,6 +65,7 @@ av equipment - wireless sender,WSEND,,IfcAudioVisualAppliance,NOTDEFINED,1
 battery,BATT,ELECTRICAL/BATT,IfcElectricFlowStorageDevice,BATTERY,0
 battery - battery trip unit,BTR,ELECTRICAL/BATT,IfcProtectiveDevice,NOTDEFINED,0
 battery - electric heater battery,EHB,ELECTRICAL/BATT,IfcElectricFlowStorageDevice,BATTERY,0
+battery - lithium ion cell,BATTLI,,IfcElectricFlowStorageDevice,NOTDEFINED,1
 beverage machine - airpot,BVAP,,IfcElectricAppliance,NOTDEFINED,0
 beverage machine - chai machine,BVC,,IfcElectricAppliance,NOTDEFINED,0
 beverage machine - coffee grinder,BVCFMG,,IfcElectricAppliance,NOTDEFINED,0
@@ -451,7 +452,6 @@ lightning protection - earthing bar,EBA,,IfcDistributionElement,NOTDEFINED,0
 lightning protection - earthing clamp,ECL,,IfcFastener,NOTDEFINED,0
 lightning protection - earthing rod,ERO,,IfcDistributionElement,NOTDEFINED,0
 lightning protection - earthing tape,ETA,,IfcDistributionElement,NOTDEFINED,0
-battery - lithium ion cell,BATTLI,,IfcElectricFlowStorageDevice,NOTDEFINED,1
 location services - beacon,LBCN,,IfcCommunicationsAppliance,NOTDEFINED,1
 meter,MTR,METERS/MTR,IfcFlowMeter,NOTDEFINED,1
 meter - electric branch meter,EBM,METERS/MTR,IfcFlowMeter,NOTDEFINED,1

BDNS_Abbreviations_Register.qmd

@@ -0,0 +1,35 @@
+---
+execute:
+  echo: false
+tbl-cap-location: bottom
+format: 
+  html:
+    page-layout: full
+toc: false
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .qmd
+      format_name: quarto
+      format_version: '1.0'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+# Building Device and Asset Naming Standards initiative
+
+{{< include release.md >}}
+
+# Abbreviations Register
+
+```{python}
+import pandas as pd
+from itables import init_notebook_mode, show
+
+init_notebook_mode(all_interactive=True)
+df = pd.read_csv("BDNS_Abbreviations_Register.csv")
+show(df, buttons=["pageLength", "csvHtml5"], lengthMenu=[20, 50, 100, 500], style="table-layout:auto;width:100%;float:left")
+```

BDNS_Governance_model.md

@@ -1,9 +1,13 @@
-
+---
+format: 
+  html: default
+  pdf: default
+---
 # Building Device and Asset Naming Standards initiative
 
-Status: *release 1.1.0*
+{{< include release.md >}}
 
-## Governance model
+# Governance model
 
 ## Background
 

BDNS_Scoping_guidelines_and_principles.md

@@ -1,18 +1,24 @@
+---
+format: 
+  html: default
+  pdf: default
+---
 
 # Building Device and Asset Naming Standards initiative
 
-Status: *release 1.1.0*
-## Scoping guidelines and principles
+{{< include release.md >}}
 
-# Context and background
+# Scoping guidelines and principles
+
+## Context and background
 
 Building data is currently structured in many different ways, with no single standard. Although several attempts have been made to introduce a universal standard, these have not been universally adopted, and have often found to be insufficiently detailed to allow automated acquisition and surfacing of data from device (both input and outputs), into a structured database for use in end user and building operator applications.
 
 The lack of standardised naming and labelling for building devices from design to operation means we are failing to leverage the value of data to allow interoperability, improve building efficiency/operations and increase occupant productivity and happiness. 
 
 A naming and labelling standard (complementing other industry initiatives) will simplify and drive consistency, thus increasing value by unlocking the application of technologies such as machine learning.  
 
-# Purpose
+## Purpose
 
 This project intends to provide an **industry wide naming convention framework** for  Information Technology (IT), Mechanical, Electrical and Public Health (MEP), and other Operational Technology (OT) devices and assets within buildings.
 
@@ -35,7 +41,7 @@ There is a number of initiatives around naming and tagging already in the indust
 
 The intent is not to replace these standards or create an overarching umbrella standard on top of existing initiatives, but to create a convention that is complementary and can address the correct naming of control system devices and associated maintainable assets (within the framework) from the early design stages through to operation, while ensuring relevance and suitability to all design and operational building stakeholders.
 
-# Scope
+## Scope
 
 The scope of this project is very focused: to provide an open naming convention and associated specifications for the naming of building control devices and associated items (within the defined framework) within buildings.
 
@@ -58,15 +64,15 @@ The naming standard is applicable to fixed equipment only. Mobile equipment such
 
 Components that are part of a device, such as fan coil unit valves and controllers are not considered to be standalone devices, and therefore do not need individual names. Their data points can however be described and named using complementary standards such as [Project Haystack](https://project-haystack.org/),  [Brick Schema](https://brickschema.org/) and the [Digital Buildings Ontology](https://github.com/google/digitalbuildings).
 
-# Deliverables
+## Deliverables
 
 The following documents have been developed as part of the scope:
 
 * A [specification for the naming syntax](BDNS_Specification_naming_syntax.md)
 * A [register of building device and asset type abbreviations](BDNS_Abbreviations_Register.csv)
 * A [governance model](BDNS_Governance_model.md) for the initiative
 
-# Principles
+## Principles
 
 The guiding principles for the standard are the following:
 
@@ -80,7 +86,7 @@ Our recommendation is to store data in shared repositories and not standalone sy
 * Consistency of device identity across phases
 * Transfer of design parameters from design model to operational models
 
-# Process
+## Process
 
 The proposed governance principles and change process are documented in the [Building Device and Asset Naming Standard Proposed Governance](https://docs.google.com/document/d/141jJWvlckhQtMX-F310I1KpWGwD7rvurKyeMpwVq_-g/edit#) document. The document includes information on the open licensing of the work being driven by this initiative, communication mechanisms and a process for consensus building.
 
@@ -89,7 +95,7 @@ In practice, the proposed change process will rely on the GitHub platform:
 * Changes to the syntax can be proposed by submitting an [issue](https://github.com/theodi/BDNS/issues) on the Github platform. Issues will be discussed and resolved on GitHub, and may be discussed additionally through the other communication mechanisms of the group, including mailing-list and semi-regular teleconferences.
 * Additions to the register can be proposed by submitting a [pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests) (PR) to the [Github repository](https://github.com/theodi/BDNS). Alternative submission mechanisms (e.g. through a mail address) may be made available if the Github PR mechanisms are deemed too technical.
 
-# Future work
+## Future work
 
 The intention is for this work to develop further to cover standardisation of naming for maintainable assets, but to exclude the naming of **metadata** and **data points**, which are meant to be named with a complementary standard, as discussed above.
 

BDNS_Specification_naming_syntax.md

@@ -1,6 +1,11 @@
+---
+format: 
+  html: default
+  pdf: default
+---
 # Building Device and Asset Naming Standards initiative
 
-Status: *release 1.1.0*
+{{< include release.md >}}
 
 # Specification for naming syntax
 

README.md

@@ -1,6 +1,6 @@
 # Building Device and Asset Naming Standards initiative
 
-Status: *release 1.1.0*
+{{< include release.md >}}
 
 This repository holds resources for an initiative to improve interoperability in building management, by focusing on standardising naming of building devices and assets.
 

_quarto.yml

@@ -0,0 +1,24 @@
+project:
+  type: website
+
+website:
+  navbar:
+    left:
+      - href: index.qmd
+      - href: BDNS_Governance_model.md
+        text: Governance
+      - href: BDNS_Scoping_guidelines_and_principles.md
+        text: Scope
+      - href: BDNS_Specification_naming_syntax.md
+        text: Naming Specification Syntax
+      - href: BDNS_Abbreviations_Register.qmd
+        text: Abbreviations Register
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+
+
+

environment.yml

@@ -0,0 +1,16 @@
+name: bdns
+# channels priority
+# see https://bioconda.github.io/
+# conda-forge has highest prioriy
+# --------------------------------- 
+# requirements for building docs
+channels:
+  - defaults
+  - conda-forge
+dependencies:
+  - python>=3.8
+  - jupyter
+  - quarto
+  - itables
+  - pyfiglet
+  - pandas

index.qmd

@@ -0,0 +1,5 @@
+---
+title: "BDNS"
+---
+
+{{< include README.md >}}

release.md

@@ -0,0 +1 @@
+<!-- This file exists for development only, without local testing fails. It is overwritten when the site is built with the current GH release. -->

styles.css

@@ -0,0 +1 @@
+/* css styles */