Merge pull request #7 from NRCan/dev

5.A Documentation Alpha (Dev)

Author: cefect

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

cancurve/bldgs/cc_bldgs_dialog.ui

@@ -7,7 +7,7 @@
     <x>0</x>
     <y>0</y>
     <width>800</width>
-    <height>800</height>
+    <height>819</height>
    </rect>
   </property>
   <property name="palette">
@@ -140,14 +140,14 @@ QTabBar::tab:selected { /* Style for selected tabs */
 &lt;html&gt;&lt;head&gt;&lt;meta name=&quot;qrichtext&quot; content=&quot;1&quot; /&gt;&lt;style type=&quot;text/css&quot;&gt;
 p, li { white-space: pre-wrap; }
 &lt;/style&gt;&lt;/head&gt;&lt;body style=&quot; font-family:'MS Shell Dlg 2'; font-size:14px; font-weight:400; font-style:normal;&quot;&gt;
-&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;Welcome to the CanCurve &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Buildings&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tool! This tool is designed to create &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Depth Damage Functions&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; (DDF) for Canadian buildings.&lt;/span&gt;&lt;/p&gt;
+&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;Welcome to the CanCurve &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Buildings Tool.&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; This tool is designed to create &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Depth Damage Functions&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; (DDF) for Canadian buildings.&lt;/span&gt;&lt;/p&gt;
 &lt;p align=&quot;center&quot; style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;img src=&quot;:/plugins/cancurve/img/icon.png&quot; /&gt;&lt;/p&gt;
 &lt;p align=&quot;center&quot; style=&quot;-qt-paragraph-type:empty; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;br /&gt;&lt;/p&gt;
 &lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;The following inputs are required:&lt;/span&gt;&lt;/p&gt;
-&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Building Metadata&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;: These standard flood-related building properties are specified on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Building Metadata&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. This metadata will be used to populate the metadata of your DDF. Some of the fields are also used in the calculation process.&lt;/span&gt;&lt;/p&gt;
-&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Cost Information: &lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;This restoration item and cost data is specifed as a CSV file on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Data Input&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. Click &lt;/span&gt;&lt;a href=&quot;https://github.com/NRCan/CanCurve/blob/main/tests/data/bldgs/case1/R_1-L-BD-CU_ABCA.csv&quot;&gt;&lt;span style=&quot; font-size:12pt; text-decoration: underline; color:#0000ff;&quot;&gt;here&lt;/span&gt;&lt;/a&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; for an example. &lt;/span&gt;&lt;span style=&quot; font-size:14px;&quot;&gt;&lt;br /&gt;&lt;/span&gt;&lt;/p&gt;
+&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Metadata&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;: These standard flood-related building properties are specified on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Metadata&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. This metadata will be used to populate the metadata of your DDF. Some of the fields are also used in the calculation process.&lt;/span&gt;&lt;/p&gt;
+&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Cost-Item Table: &lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;This table of restoration items and their costs is specifed as a CSV file on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Data Input&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. Click &lt;/span&gt;&lt;a href=&quot;https://github.com/NRCan/CanCurve/blob/main/tests/data/bldgs/case1/R_1-L-BD-CU_ABCA.csv&quot;&gt;&lt;span style=&quot; font-size:12pt; text-decoration: underline; color:#0000ff;&quot;&gt;here&lt;/span&gt;&lt;/a&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; for an example. &lt;/span&gt;&lt;span style=&quot; font-size:14px;&quot;&gt;&lt;br /&gt;&lt;/span&gt;&lt;/p&gt;
 &lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;The following inputs are optional:&lt;/span&gt;&lt;/p&gt;
-&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Depth-Replacement-Factor (DRF) dataset&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;: This dataset relates flood depth to the percentage loss or damage of a restoration item and is specified on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Data Input&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. By default, the DRF dataset shipped with CanCurve will be used.&lt;/span&gt;&lt;/p&gt;
+&lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt; font-weight:600;&quot;&gt;Depth Replacement-Factor (DRF) dataset&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;: This dataset relates flood depth to the percentage loss or damage of a restoration item and is specified on the &lt;/span&gt;&lt;span style=&quot; font-size:12pt; font-style:italic;&quot;&gt;Data Input&lt;/span&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt; tab. By default, the DRF dataset shipped with CanCurve will be used.&lt;/span&gt;&lt;/p&gt;
 &lt;p style=&quot;-qt-paragraph-type:empty; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-size:12pt;&quot;&gt;&lt;br /&gt;&lt;/p&gt;
 &lt;p style=&quot; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;&quot;&gt;&lt;span style=&quot; font-size:12pt;&quot;&gt;Navigate through the tabs at the top of the window from left-to-right to create your own DDF.&lt;/span&gt;&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
          </property>
@@ -201,7 +201,7 @@ p, li { white-space: pre-wrap; }
      </widget>
      <widget class="QWidget" name="tab2bldgDetils">
       <attribute name="title">
-       <string>Building Metadata</string>
+       <string>Metadata</string>
       </attribute>
       <layout class="QVBoxLayout" name="verticalLayout_7">
        <item>
@@ -220,7 +220,7 @@ p, li { white-space: pre-wrap; }
           <property name="geometry">
            <rect>
             <x>0</x>
-            <y>-317</y>
+            <y>0</y>
             <width>745</width>
             <height>976</height>
            </rect>
@@ -364,7 +364,7 @@ QGroupBox {
                 <item row="9" column="0">
                  <widget class="QLabel" name="buildingLayoutLabel">
                   <property name="text">
-                   <string>Building Layout</string>
+                   <string>Building Layout*</string>
                   </property>
                  </widget>
                 </item>
@@ -413,7 +413,7 @@ QGroupBox {
                 <item row="1" column="0">
                  <widget class="QLabel" name="basementHeightLabel_2">
                   <property name="text">
-                   <string>Basement height (value)</string>
+                   <string>Basement height (value)*</string>
                   </property>
                  </widget>
                 </item>
@@ -505,14 +505,14 @@ QGroupBox {
                    <string>This value is used when 'RCV/Area' is selected to scale the replacement costs (e.g., to footprint area)</string>
                   </property>
                   <property name="text">
-                   <string>Area (value)</string>
+                   <string>Structure area (value)*</string>
                   </property>
                  </widget>
                 </item>
                 <item row="2" column="0">
                  <widget class="QLabel" name="qualityOfBuildingMaterialsLabel">
                   <property name="text">
-                   <string>Quality of Building Materials</string>
+                   <string>Quality of building materials</string>
                   </property>
                  </widget>
                 </item>
@@ -726,7 +726,7 @@ QGroupBox {
        <item>
         <widget class="QLabel" name="label_6">
          <property name="text">
-          <string>On this page, you'll load the data needed for CanCurve to create the depth-damage function</string>
+          <string>Specify the settings and datasets for your project</string>
          </property>
         </widget>
        </item>
@@ -797,7 +797,7 @@ QGroupBox {
        <item>
         <widget class="QGroupBox" name="groupBox_t03_03">
          <property name="title">
-          <string>Cost-Item File:</string>
+          <string>Cost-Item Table:</string>
          </property>
          <layout class="QHBoxLayout" name="horizontalLayout_9">
           <item>
@@ -948,7 +948,7 @@ QGroupBox {
        <item>
         <widget class="QGroupBox" name="groupBox_t03_06">
          <property name="title">
-          <string>Depth-Replacement-Fraction File</string>
+          <string>Depth Replacement-Factor (DRF) Database:</string>
          </property>
          <layout class="QHBoxLayout" name="horizontalLayout_11">
           <item>
@@ -1403,6 +1403,9 @@ QLabel {
                    <verstretch>0</verstretch>
                   </sizepolicy>
                  </property>
+                 <property name="toolTip">
+                  <string>build project SQLite database and load data into it</string>
+                 </property>
                  <property name="text">
                   <string>Run</string>
                  </property>
@@ -1511,6 +1514,9 @@ QLabel {
                    <verstretch>0</verstretch>
                   </sizepolicy>
                  </property>
+                 <property name="toolTip">
+                  <string>Join DRF to CI then multiply through to create fractional restoration costs</string>
+                 </property>
                  <property name="text">
                   <string>Run</string>
                  </property>
@@ -1600,6 +1606,9 @@ QLabel {
                    <verstretch>0</verstretch>
                   </sizepolicy>
                  </property>
+                 <property name="toolTip">
+                  <string>group by story and assemble DDF</string>
+                 </property>
                  <property name="text">
                   <string>Run</string>
                  </property>
@@ -1948,7 +1957,7 @@ QLabel {
  </resources>
  <connections/>
  <buttongroups>
-  <buttongroup name="buttonGroup_runControl"/>
   <buttongroup name="buttonGroup_costbasis"/>
+  <buttongroup name="buttonGroup_runControl"/>
  </buttongroups>
 </ui>

cancurve/bldgs/core.py

@@ -642,7 +642,7 @@ def c00_setup_project(
 
 
         ):
-    """build project SQLite. load data into it
+    """build project SQLite database and load data into it
     
     
     Params
@@ -923,7 +923,7 @@ def c00_setup_project(
 def c01_join_drf(proj_db_fp,        
         log=None, 
         ):
-    """Join DRF to CI then multiply through to create 'depth_rcv' table
+    """Join DRF to CI then multiply through to create fractional restoration costs
     
     
     Params

dev_tools/docs_build.bat

@@ -0,0 +1,26 @@
+:: Building CanCurve sphinx documentation (w/o RTD)
+
+ 
+
+:: activate docs environment
+call l:\09_REPOS\01_COMMON\sphinx\env\conda_activate.bat
+
+:: call the shpinx make script
+:: call %~dp0..\docs\make.bat html
+:: difficult to customize
+
+
+:: change to documentation
+ 
+cd %~dp0..\docs
+
+:: call builder CLI
+ECHO on
+ 
+sphinx-build -M html .\source .\build --jobs=4 --verbose --show-traceback --nitpicky --warning-file=.\build\sphinx_warnings.txt
+
+
+:: launch it
+call build\html\index.html
+
+cmd.exe

docs/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+#CanCurve documentation
+
+CanCurve uses Sphinx and ReadTheDocs
+
+## build sphinx documentation locally
+need a python environment w/ sphinx
+call .\dev_tools\docs_build.bat

docs/cspell.json

@@ -0,0 +1,32 @@
+{
+    "language": "en-CA",
+    "dictionaries": ["en-CA"],
+    "dictionaryDefinitions": [
+        {
+            "name": "en-CA",
+            "path": "l:\\09_REPOS\\01_COMMON\\sphinx\\env\\sphinx\\node_modules\\@cspell\\dict-en-ca\\en_CA.trie"
+        }
+    ],
+    "enableFiletypes": [
+        "rst"
+    ],
+    "ignoreRegExpList": [
+        "/<[^>]*>/g",  // Ignore text within angle brackets
+        "/^\\../"  // Ignore lines that begin with ..
+    ],
+    "ignorePaths": [
+        "package-lock.json",
+        "node_modules",
+        "vscode-extension",
+        ".git/objects",
+        ".vscode",
+        ".vscode-insiders",
+        ".settings"
+    ],
+    "userWords": [
+        "operationalize",
+        "QGIS",
+        "Xactimate",
+        "DDFP"
+    ]
+}

docs/source/01_getting-started.rst

@@ -0,0 +1,90 @@
+.. _sec01-gettingStarted:
+
+Getting Started
+==================
+The following sections will help you get started using CanCurve.
+We suggest reading these sections first.
+
+
+.. _sec01-install:
+
+Installation
+------------
+
+To install CanCurve, you first need to install QGIS, then you can install CanCurve from the Plugin Repository.
+
+For detailed instructions, refer to the `project README <https://github.com/NRCan/CanCurve/tree/main?tab=readme-ov-file#installation>`_.
+For best performance, ensure you have the specified version of QGIS installed.
+
+
+.. _sec01-overview:
+
+Overviews
+-----------------------
+CanCurve is a collection of tools for generating Depth Damage Functions (DDF) used by platforms like `CanFlood <https://github.com/NRCan/CanFlood>`_ to create flood risk models.
+CanCurve's :ref:`Buildings Tool <sec02-bldgs>` for example facilitates the creation of DDFs from detailed restoration cost data for archetypal buildings.
+This tool joins a table of restoration activities (e.g., repair dry-wall for $1000), called the :ref:`Cost-Item Table <sec02-costItem>`, to a database of information on the flood vulnerability of those items, called the :ref:`Depth-Replacement-Factor (DRF) Database <sec02-DRF>`.
+After identifying the target building or archetype for which a user would like to construct a DDF, typically a :ref:`Cost-Item Table <sec02-costItem>` is prepared using local pricing tables and expert knowledge on the restoration of the building.
+For the :ref:`DRF Database <sec02-DRF>`, either the version shipped with CanCurve can be used (default), or an alternate file can be specified.
+Once these inputs and the building metadata are prepared and entered into the Buildings Tool, the four :ref:`Curve Creation <sec02-Core>` steps can be run to create and export a DDF in :ref:`CanFlood format <sec02-CanFloodFormat>`.
+
+
+
+
+
+.. _sec01-quick:
+
+Quick-Start
+-----------------------
+After installation of the plugin, the |CanCurve_icon| icon should appear on your plugins toolbar.
+If you don't see the icon, first ensure the plugin is checked on the **Installed** tab of the **Manage and Install Plugins..** dialog; then ensure the **plugins toolbar** is enabled by right-clicking the QGIS toolbar.
+
+.. |CanCurve_icon| image:: /assets/icon_solid.png
+   :align: middle
+   :width: 14
+
+To start working with CanCurve, click the |CanCurve_icon| to open the :ref:`Buildings Tool <sec02-bldgs>` dialog.
+
+
+.. _fig01-dialog-welcome:
+
+.. figure:: /assets/01-dialog-welcome.png
+   :alt: Welcome Tab
+   :align: center
+   :width: 900px
+
+   Welcome tab of the Buildings Tool.
+
+
+To use the tool to create a DDF from data for your archetypal building, first populate the **Metadata** tab with whatever information is available (see the :ref:`Tutorials <sec03-tutorials>` section for example data).
+Note only fields marked with an asterisk (*) are required, but the more information you provide, the more complete your DDF will be.
+To specify settings, the :ref:`Cost-Item Table <sec02-costItem>`, the :ref:`Depth-Replacement Factor (DRF) Database <sec02-DRF>`, and the :ref:`Fixed Costs <sec02-fixedCosts>` data, complete the **Data Input** tab.
+Finally, the four curve creation steps can be executed from the **Create Curve** tab, ending in an export of your DDF in :ref:`CanFlood format <sec02-CanFloodFormat>`.
+
+
+See the :ref:`User Guide <sec02-userGuide>` and the :ref:`Tutorials <sec03-tutorials>` section to learn more.
+
+
+.. _sec01-faq:
+
+Frequently Asked Questions
+--------------------------
+
+**Where can I find Cost-Item data for my archetype?**
+    Typically this information is obtained from cost restoration experts using specialized software like Xactimate and a detailed model of the structure.
+
+**How can I add entries to my Depth-Replacement-Factor (DRF) Database**
+    You'll need to use some software that allows editing of SQLite databases. We recommend `DB Browser for SQLite <https://sqlitebrowser.org/>`_.
+
+**Where can I go to get help?**
+    The best place to get help is the `CanCurve GitHub Issues <https://github.com/NRCan/CanCurve/issues>`_ page where you can read through questions posted by others or ask your own.
+
+
+**Do I really need to install an old version of QGIS to use CanCurve**
+      No, but we recommend it for best performance. If you have a newer version of QGIS installed, you can try CanCurve with it, but you may experience issues.
+
+      
+
+
+
+