Add initial jupyter book docs

[gtfierro]

1 basic, but complete tutorial

Another one on the way. Working with pySHACL try and make it easier for BuildingMOTIF to give feedback on shapes (see https://github.com/RDFLib/pySHACL/pull/165). Second tutorial isn't done yet as a result, but I figure I'd push this, just so we can all make progress

---

Close #159. Structure based on Diataxis Framework (# 2-5 below).

1. Main page/file
   • [x] Future README with links to parts of documentation.
2. Tutorials
   • Tutorial 1. Model Creation
     • [x] Model creation
   • Tutorial 2. Model Validation
     • [x] Model validation (ontology) PASS
     • [x] Model validation (manifest) FAIL, FIX (manually), then PASS
     • [x] Model validation (use case, G36) FAIL (needs #179 and #180 to be merged)
   • Tutorial 3. Model Correction
     • [x] Model validation (use case, G36) FAIL, FIX (auto), then PASS
   • Tutorial 4. Writing Templates
     • [x] done
3. How-to Guides
   • TODO in future PR
4. Reference
   • [x] Developer Documentation (current README)
   • [x] API Documentation (Sphinx autodoc)
5. Explanation
   • TODO in future PR
6. Bibliograhpy
   • [x] bibtex of BuildingMOTIF publications

[MatthewSteen]

I'll be able to look at this next week but feel free to merge without my review if needed.

[TShapinsky]

Small note. You use tool.poetry.group.dev.dependencies to add jupyter-book as a dependency. This is definitely the right way in poetry 1.2 but is unsupported in 1.1. I'm fine updating my local poetry to 1.2, but wanted to make a note in case anyone else has issues.

[MatthewSteen]

Here's a rough outline that Toby and I brainstormed. Each section below would be a separate file/page.

Getting Started

Setup BuildingMOTIF.

• Installation for users, i.e. Binder, Colab, and/or Docker instructions.
• Keep dev setup in repo README?
• For the first public release we could just link to the README.

Introduction

Core parts of BuildingMOTIF and high level architecture?

• Models
• Libraries
• Templates
• Shapes
• Manifests

Basic Tutorial

Demonstrate core features by (1) creating a simple model of the DOE Small Office and (2) validating it.

1. Create Model with Templates and Validate It

1. Create new (empty) model.
2. Load Brick Library, list templates
3. Create simple model using templates.
   • (5) Rooms
   • (5) HVAC Zones
   • (5) AHUs
     • CAV fan
     • DX clg and htg coils (heat pump) - MISSING IN BRICK
     • CAV terminal
4. Validate that model is valid Brick model

2. Use Case Validatation (Guideline 36)

1. Load previous model
2. Load library, find shape(s), selecting shapes
3. Validate for ? (fail)
4. Fix
5. Validate for ? (pass)

Intermediate Tutorial

Supported Use Cases

Advanced Example - in progress use-cases, e.g. BACnet.

[MatthewSteen]

Gabe - I added my start to the 4.8 shapes. Please take it from here, thanks!

[gtfierro]

Came across https://diataxis.fr today -- could help for framing how to organize the sections of the JupyterBook

[MatthewSteen]

Came across https://diataxis.fr today -- could help for framing how to organize the sections of the JupyterBook

That looks like a great resource. I haven't been able to find a standard documentation format with some quick searches so let's use Diataxis.

[gtfierro]

@MatthewSteen I think the G36 templates/shapes are probably done on this. How much of the rest of the documentation do we want to flesh out in this PR vs subsequent PRs?

[MatthewSteen]

@gtfierro see my checklist at the top. I think this PR should just be for the two tutorials using the "small office" model with the first (ontology) validation passing and the second (G36 sz vav ahu) validation failing. Then, depending on the length, we can add a third tutorial for fixing a model that fails or add to the 2nd if short. Thoughts?

[MatthewSteen]

Here's the current HTML build.

• html.zip.txt

[MatthewSteen]

I think this is close to done. Here's the latest build in case it's helpful for reviewing. FYI @avijitsaha.

• html.zip.txt

---

After this is merged in, I'd like to do the following in another PR.

• Move files from /book > /doc
• Set up GitHub Pages for the repo's domain where the docs will live

[MatthewSteen]

@gtfierro and @TShapinsky any major comments? I'd like to get this merged in soon. I think we can make final changes in a separate PR.

[gtfierro]

I'm good to merge!