-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #7 from NRCan/dev
5.A Documentation Alpha (Dev)
- Loading branch information
Showing
28 changed files
with
579 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -69,7 +69,7 @@ instance/ | |
| .scrapy | ||
|
|
||
| # Sphinx documentation | ||
| docs/_build/ | ||
| docs/build/ | ||
|
|
||
| # PyBuilder | ||
| target/ | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| ] | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
Oops, something went wrong.