From 24e7d1d1f46e695e53ad1779c0919fa17c9740b2 Mon Sep 17 00:00:00 2001 From: Matt Reimer Date: Thu, 14 Dec 2023 10:35:57 -0800 Subject: [PATCH] adding riverscapesXML and riverscapes.net content for migration --- content/page/MIGRATED/About/index.mdx | 23 ++ .../Data_Warehouses/gettingaround.mdx | 4 +- .../Riverscapes_Projects/Program/index.md | 80 +++++ .../Project/datasources.md | 136 ++++++++ .../Riverscapes_Projects/Project/guids.md | 94 +++++ .../Riverscapes_Projects/Project/metadata.md | 85 +++++ .../Project/project-links.md | 60 ++++ .../Project/projectxml.md | 249 +++++++++++++ .../Project/realizations.md | 172 +++++++++ .../Riverscapes_Projects/index.md | 117 +++++++ .../Riverscapes_Projects/xml_validation.md | 67 ++++ .../Source_Code/index.md | 70 ++++ .../WebSites/Common.md | 245 +++++++++++++ .../WebSites/Consistency.md | 64 ++++ .../ReportCards/Tool_ReportCard_0-0-00.md | 100 ++++++ .../WebSites/ReportCards/index.md | 23 ++ .../WebSites/bibliographies.md | 62 ++++ .../WebSites/creating_new_pages.md | 17 + .../Documentation_Standards/WebSites/edits.md | 33 ++ .../Documentation_Standards/WebSites/index.md | 57 +++ .../WebSites/styleguide.md | 329 ++++++++++++++++++ .../WebSites/subdomain.md | 35 ++ .../WebSites/testing_locally.md | 93 +++++ .../WebSites/theming.md | 59 ++++ .../WebSites/writing_content.md | 129 +++++++ .../Documentation_Standards/index.md | 54 +++ .../Tools/Technical_Reference/database.md | 66 ++++ .../Tools/Technical_Reference/videos.md | 44 +++ content/page/MIGRATED/Tools/discrimination.md | 140 ++++++++ content/page/MIGRATED/Tools/index.mdx | 133 +++++++ content/page/MIGRATED/Tools/reportcards.mdx | 43 +++ content/page/MIGRATED/Tools/toolStandards.mdx | 27 ++ .../page/MIGRATED/Tools/valueproposition.md | 25 ++ content/page/demo.mdx | 69 +++- package.json | 2 +- yarn.lock | 214 +++++++++++- 36 files changed, 3210 insertions(+), 10 deletions(-) create mode 100644 content/page/MIGRATED/About/index.mdx create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Program/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/datasources.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/guids.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/metadata.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/project-links.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/realizations.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/xml_validation.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Source_Code/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Common.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Consistency.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/bibliographies.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/creating_new_pages.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/edits.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/styleguide.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/subdomain.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/testing_locally.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/theming.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/writing_content.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/index.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/database.md create mode 100644 content/page/MIGRATED/Tools/Technical_Reference/videos.md create mode 100644 content/page/MIGRATED/Tools/discrimination.md create mode 100644 content/page/MIGRATED/Tools/index.mdx create mode 100644 content/page/MIGRATED/Tools/reportcards.mdx create mode 100644 content/page/MIGRATED/Tools/toolStandards.mdx create mode 100644 content/page/MIGRATED/Tools/valueproposition.md diff --git a/content/page/MIGRATED/About/index.mdx b/content/page/MIGRATED/About/index.mdx new file mode 100644 index 0000000..4036754 --- /dev/null +++ b/content/page/MIGRATED/About/index.mdx @@ -0,0 +1,23 @@ +--- +title: About RC +description: About the Riverscapes Consortium +banner: true +--- + +## Overview of Riverscapes Consortium + +In this less than five minute video we introduce the Riverscape Consortium. + + + +## More Elaborate Background + +This half hour video is based on [Joe Wheaton's](http://joewheaton.org) talk at a workshop in Lyon, France in December of 2019 on Regionalized Fluvial Geomorphology (see [original slides](https://www.researchgate.net/publication/338225952_Riverscapes_Consortium_to_Leverage_Advances_in_Other_Regions_in_your_Regionalization)). It lays out some of the key concepts and part of the motivation for the Riverscapes Consortium and why it we are developing data standards and workflows. + + + +## Talk about Need for Riverscapes Consortium and Standards + +The Riverscape Consortium's [Joe Wheaton](http://joewheaton.org) was awarded the [British Society for Geomorphology's](https://twitter.com/BSG_Geomorph) 2020 [Gordon Warwick Award](https://www.geomorphology.org.uk/awards) for excellence in geomorphic research. In his talk below, he discusses the need for the sort of standards and community embodied in the Riverscape Consortium to rise to the challenge of the scope of riverscape degradation. + + diff --git a/content/page/MIGRATED/Data_Warehouses/gettingaround.mdx b/content/page/MIGRATED/Data_Warehouses/gettingaround.mdx index a158b96..1115706 100644 --- a/content/page/MIGRATED/Data_Warehouses/gettingaround.mdx +++ b/content/page/MIGRATED/Data_Warehouses/gettingaround.mdx @@ -38,7 +38,9 @@ We show you how to navigate and view the Programs you have been granted access ### Access - Types - All users have access to the "[Public Data](https://data.riverscapes.net/#/PUBLIC_DATA)". Each account has four different access levels defined in every Program: + + +All users have access to the "[Public Data](https://data.riverscapes.net/#/PUBLIC_DATA)". Each account has four different access levels defined in every Program: 1. `No Access` - By default users do not have access to any other programs but the [Public Data](https://data.riverscapes.net/#/PUBLIC_DATA) 2. `Observer` - This provides basic read-only access to a Program. diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Program/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Program/index.md new file mode 100644 index 0000000..9be7818 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Program/index.md @@ -0,0 +1,80 @@ +--- +title: Program XML +--- + +### Quick Link: + +Validating your `program.xml` file can be done using the following URL: + +``` +https://raw.githubusercontent.com/Riverscapes/Program/master/Program/XSD/V1/Program.xsd +``` + +like so: + +``` xml + + +``` + +## Background: + +We need a way to represent the bucket file structure and hold that structure +programatically so that products can find their homes when they upload and also +so users can find the products they care about. + +The following is meant to completely describe the ideas of the following document: + + +So according to this, you would be able to find the output of a fuzzy FHM product like so: +`/ColumbiaRiverBasin/JohnDay/Sites/CBW05583-028079/VISIT_1029/2012/Q_001/Analyses/Fuzzy/Steelhead/Spawner/FHM/outputs/fuzzyHSI.tif` + +We do this using some basic building blocks: + +* ` `: A container is a folder literally called what the name is "Network" in this case +* ` `: A level will have repeating elements. So instead of "Watershed" you'll have lots + of folders, each wih the name of the Level (Watershed in this case) in question/ +* `` : Products are the endpoint. If I can find a product then I can download or upload a whole project + +```xml + + + + riverscapesdata + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/datasources.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/datasources.md new file mode 100644 index 0000000..664a5f4 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/datasources.md @@ -0,0 +1,136 @@ +--- +title: DataSources (Inputs/Outputs) +weight: 3 + +--- + +DataSources can be defined in two places: + +1. **Inside** **`` At the top of the file**: These are DataSources that can be referenced from other places. +2. **Inside a realization**: This can either be a reference to the input at the top of the file or a completely new DataSource node. + + +## Dataset Type Hierarchy + +The kind of Datasource tag you choose (e.g. ``, `` ) is important. The list below may not be extensive since new tags may be invented from time to time. + +1. **DataSet**: *This is a grouping only and not in use as a tag* + 1. **GeoSpatial**: *This is a grouping only and not in use as a tag* + 1. **Raster**: `` + 1. **DEM**: `` + 2. **Vector**: `` + 3. **TIN**: `` + 2. **Context Layer**: A context layer can either be a file OR a tile-layer loaded from a mapping service + 1. **Hillshade**: ``: Path to a hillshade raster or tile service. + 2. **Shape**: A `.shp` file that is not used for context and not geospatial processing. + 3. **SimpleFile** + 1. **CSV**: Self-explanatory + 2. **Image**: Any image (png, jpg, gif etc.) + +## General Use + +**Here is an example of a DataSource** + +```xml + + Hillshade + analyses\context\layers\hillshade\Upper_Salmon_Hillshade.tif + ../../Relative/path/to/OtherProject + +``` + +### Attributes: + +* **Guids**: `Guid=""` All inputs that are not references (i.e. using the `ref=""` attribute) must have a Guid. +* **Id**: `id=""` The Id you give to a Datasource should be unique in the XML file but does not have to be unique across all project XMLs. +* **References**: `ref=""`: The `ref` attribute is used to reference a DataSource inside the `` tag at the top of the file. It should contain the unique `id` of the DataSource you would like to reference. + +#### Rerences (`ref=""`) + +**Some rules for using `ref`** + +* If you use `ref` you should not use `Id` or `Guid` since these are covered inside the referenced object. Likewise you should not use ``, ``, `` or any other tags. +* `` can still be used but only if it is refering to information that cannot be shared across all [Realizations](). + +``` xml + + + + + + DEM + 01_Inputs/01_Topo/Slope/Slope1.img + + Jordan Gilbert + 17020005 + + + + + + + + + + + + + + + + +``` + +### Elements: + +* **Name**: `` A plain-text name for this Datasource +* **Path**: `` A ***RELATIVE*** filepath to the layer/file/datasource in question (i.e. `inputs/input01/input.tif`). The path is relative either to this project or another project root specified using the `` element. +* **Project**: ``*(Optional)* If you are refering to a datasource in another project you can use this element. Relative paths are preferred but in some cases absolute paths are necessary. See below for more details. +* [**MetaData**](metadata.html): `` Key-value pairs. *(See [MetaData](metadata.html) docs for how to use this.)* + +#### Special Elements: + +* **URL**: *(Contextual Layers Only)* Contextual layers like `` can have this element. It is the path to an online location or tile-server. The idea is that the software can try to load the local file and, failing this, use the version available from the `` + +## External Project References + +You can use Datasources from other projects using the `` element + +* Relative paths are prefered. Absolute paths can be used but will break when transfered to another machine. +* You *must* specify a path to a FOLDER contianing the `project.rs.xml` file: `../../Path/to/Project/` + +## Extended Use + +Sometimes you'll see a tag inside an `` tag that is Dataset-like. An example is VBET where a drainage network `` is basically a shapefile Dataset Type that has been extended to contain `` + +```xml + + + + + + + + + + + + + Large Buffer + 01_Inputs/02_Network/Network_001/Buffers/lg_buf1.shp + + + Medium Buffer + 01_Inputs/02_Network/Network_001/Buffers/med_buf1.shp + + + Small Buffer + 01_Inputs/02_Network/Network_001/Buffers/sm_buf1.shp + + + + + +``` + +Such examples are too specific to document fully here. You can find hints at how to use these using autocomplete in Pycharm or by reading the XSD file. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/guids.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/guids.md new file mode 100644 index 0000000..5869be0 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/guids.md @@ -0,0 +1,94 @@ +--- +title: GUIDs +weight: 1 +--- + +[Universally Unique Identifiers (UUID, or GUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) Are used to track file changes on XML nodes. + +``` +07817542-0b3f-4154-9bfb-d3e20cc69d64 +740ce55d-91f7-47bd-b3e7-265d685a464d +174fd928-34a1-462f-ae60-8a6d3109c97b +c767a4b0-74db-49d2-bfbf-8b6d3a77b3d5 +603ee6e2-a70d-4514-adf0-7335b9800743 +b5b5bb74-7dbd-468d-a863-a026b36a0224 +385c98ec-811c-4dd0-8990-3b92c33f3f5b +1f819399-1f97-4cec-a8d7-b5180aca6221 +f0b50bdc-e302-4647-ae04-98f561f90b38 +412332d4-89a0-4acb-a7ae-2826f8717b55 +``` + +## Guidelines for GUID use + +### DO use GUIDs: + +* Uniquely. Every GUID inside an XML file should be unique. There is one case where GUIDs can be duplicates: when you are referencing a layer from another project. +* On every file node for inputs and outputs: (`, etc...`) +* On Every Realization +* On inputs pulled from other projects. **Note: GUIDs must match.** + +### DON'T use GUIDS: + +* On container nodes (``) +* On internal references: (``) + +### DO Change a GUID + +* Any time the file on the disk is altered in any way. + +## Examples: + +``` xml + + + + Slope + 01_Inputs/01_Topo/Slope/Slope1.img + + + + + + + ... + + + + + + USal_valley_bottom + inputs/USal_valleybottom.shp + ../some/../other/path/Sample_VBET_Project/ + + +``` + + + +## Code Examples: + +### Python: + +```python +import uuid + +def getUUID(self): + """ + Here's a little function that prints a unique ID (GUID) + """ + return str(uuid.uuid4()).upper() + +print getUUID() +``` + +Note that this uses `.upper()` to create windows-like GUIDs that are all uppercase. It shouldn't matter that much whether you create upper or lowercase GUIDs so long as you are consistent. + + + +### Fetching Guids + +When you're linking projects together you might need to fetch a guid from anothe project. + +The following snippet shows 3 different ways to retrieve a guid from a project: + + \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/metadata.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/metadata.md new file mode 100644 index 0000000..4524a6f --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/metadata.md @@ -0,0 +1,85 @@ +--- +title: MetaData +weight: 2 + +--- + +# MetaData + +Metadata tags can be used in a few key places inside the Project XML: + +1. Directly inside `` + +```xml + + SomeVal + SomeOtherVal + +``` + +## Where to use: + +Metadata tags can be used in a few key places in the Project XML: + +### Directly inside `` + +Project-wide metadata is designed to give context to the entire project: + +```xml + + + + Sample_VBET_Project + VBET + + + Jordan Gilbert + 17020005 + Chief Joseph + 17020005 + Upper Columbia + SomeOtherValue + + + + + +``` + +### Inside Realizations + +Anything that is unique to this particular realization should be stored as such: + +```xml + + + + My realization Name + + + Hello + I did a thing and then another thing... + + + + + + +``` + +### Inside Datasource Objects + +Can be used to add important data to the specific DataSource + +```xml + + DEM + 01_Inputs/01_Topo/Slope/Slope1.img + + Jordan Gilbert + 2016-07-08T23:49:51 + + +``` + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/project-links.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/project-links.md new file mode 100644 index 0000000..e1e7f58 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/project-links.md @@ -0,0 +1,60 @@ +--- +title: Linking to other projects +--- + +Sometimes you need to grab resources like inputs and reference layers from other projects. You do it like so: + +## Case 1: Internally referenced file + +This is the non-linked case just for clarity. + +``` xml + + USal_valley_bottom + valley_bottom_polygon_01/USal_valleybottom.shp + + /inputs/confinements/valley_bottom_polygon/valley_bottom_polygon_01/USal_valleybottom.shp + + +``` + +## Case 2: Non-local, non-program file + +Sometimes you just want to grab a file from somewhere on your computer. + +This is exactly the same as **Case 1** because it is up to the software to copy this layer into the project and link it up + +## Case 3: Grab an input from an external project in the same program + +``` xml + + USal_valley_bottom + + ../some/../other/path/Sample_VBET_Project + + inputs/confinements/valley_bottom_polygon/valley_bottom_polygon_01/USal_valleybottom.shp + +``` + +*NB: The `` tab references a folder, not an XML file* + +## Case 4: Grab a file from an external project on another drive or outside the program + +In this case all you need to do is use an absolute path. + +This case is here but it shouldn't be used if you can help it because it can't really be shared and has cross-platform implications.\ + +``` xml + + USal_valley_bottom + c:\some\other\project\Sample_VBET_Project + confinements\valley_bottom_polygon\valley_bottom_polygon_01\USal_valleybottom.shp + +``` + +## Notes: + +* `` is ALWAYS relative. No exceptions +* `` is usually relative. Exceptions can be made but should be avoided if possible. It references a folder containing the project XML file (`project.rs.xml`) +* Referencing the parent's guid is a good practice. See the [Guid guidelines](guids.html) page for examples of how fetch guids from other projects. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.md new file mode 100644 index 0000000..9f32a05 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.md @@ -0,0 +1,249 @@ +--- +title: The Project XML +weight: 1 +--- + +### Quick Link: + +Validating your `project.rs.xml` file can be done using the following URL: + +``` +https://raw.githubusercontent.com/Riverscapes/Program/master/Project/XSD/V1/Project.xsd +``` + +like so: + +``` xml + + +``` + +## General: + +The Project XML structure is used by every type of Project in the RiverScapes Family. Each project has the same base structure and can be customized at lower levels to accommodate the custom + + +**Here is an example of a project file skeleton:** + +``` xml + + + + RiverStylesProject1 + RiverStyles + + + SomeVal + + + + + + + + + + USal_confinement_500m + + + 500 + + + + + + + + + + + + + + + + +``` + +## Project: `` + +The `` tag is the root of the project XML and must reference the XSD (in a versioned folder) it can contain: + +* **Name**: The string that is the project name +* **ProjectType**: A string containing the type of project this is (e.g. `VBET` or `GCD`). This will be used when parsing the XML file for things like choosing how to display it in the Toolbar. +* [**MetaData**](../metadata): is anything associated with this project that gives it context. +* [**Inputs**](../datasources): The top-level inputs are [datasources](../datasources) that are shared amongst all the realizations. +* **Realizations**: The realizations are the "runs" of the tool. Everything you need to know about the inputs, parameters and outputs for that particular "run" should be contained here. + + +## Realizations: `` + +Inside the realzations tag you will find a custom tag based on what kind of project this is. These contents of these custom tags have the same structure at the base level however they can be customized inside their Inputs and Analysis tags. + +***NB: Documenting all possible realizations here would be problematic because they tend to change fairly often. You can use Pycharm's autocomplete to hint at this structure, finding a simimlar XML file to use as a template, or by reading the XSD directly.*** + +### Basic structure + +```xml + + Some realization name + + + ParamValue + + + + + + + + + + + +``` + +#### Attributes: + +* **Guid**: Unique across all projects +* **Id:** Text id for use with folder naming etc. +* **ProductVersion**: The version of the tool used to create this realization. +* **DateCreated**: Date code for when this realization was created. Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format(e.g. `2016-07-08T23:49:51`) + +#### Elements: + +* **Name**: A good name for this realization. +* **Parameters**: Key-Value pairs for any parameters that were used to run this tool and create this realization. (e.g. `0.341`) +* **Inputs**: The structure inside inputs is custom to the project type but at inner-most level will use a [Datasource type](/) or a [DataSource Reference](). + +**Riverstyles Example:** + +```xml + + + USal_confinement_500m + + + 500 + + + + + + + + + + + + + + + + + + + + + + + + USal_confinement_500m + analyses\confinements\confinement_01\USal_Confinement_500m.shp + + 500 + + + + + + + + + + analyses\river_styles\manual_crosschecks\manual_crosscheck_01\USal_River_Styles.shp + + + + + + + +``` + + + +**VBET Example**: + +```xml + + + + My realization Name + + + Hello + I did a thing and then another thing... + + + + 250 + 25 + 500 + 150 + 25 + 8 + 5 + 7 + 12 + 150 + 30000 + 30000 + + + + + + + + + + + + Large Buffer + 01_Inputs/02_Network/Network_001/Buffers/lg_buf1.shp + + + Medium Buffer + 01_Inputs/02_Network/Network_001/Buffers/med_buf1.shp + + + Small Buffer + 01_Inputs/02_Network/Network_001/Buffers/sm_buf1.shp + + + + + + + My First Analysis + + + Raw Valley Bottom + 02_Analyses/Output_001/Tucannon_VBET_unedited.shp + + + Edited Valley Bottom + 02_Analyses/Output_001/Tucannon_VBET_edited.shp + + + + + +``` + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/realizations.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/realizations.md new file mode 100644 index 0000000..ffefd17 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/realizations.md @@ -0,0 +1,172 @@ +--- +title: Realizations +weight: 4 +--- +Inside the realzations tag you will find a custom tag based on what kind of project this is. These contents of these custom tags have the same structure at the base level however they can be customized inside their Inputs and Analysis tags. + +***NB: Documenting all possible realizations here would be problematic because they tend to change fairly often. You can use Pycharm's autocomplete to hint at this structure, finding a simimlar XML file to use as a template, or by reading the XSD directly.*** + +### Basic structure + +```xml + + + Some realization name + + + ParamValue + + + + + + + + + + + + +``` + +#### Attributes: + +* **Guid**: Unique across all projects +* **ProductVersion**: The version of the tool used to create this realization. +* **DateCreated**: Date code for when this realization was created. Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format(e.g. `2016-07-08T23:49:51`) +* **Promoted**: *(Optional)* Tag one of your realizations as `Promoted="true"` to make this the "Accepted" or QA-approved realization if applicable. + +#### Elements: + +* **Name**: A good name for this realization. +* **Parameters**: Key-Value pairs for any parameters that were used to run this tool and create this realization. (e.g. `0.341`) +* **Inputs**: The structure inside inputs is custom to the project type but at inner-most level will use a [Datasource type](/) or a [DataSource Reference](). + +**Riverstyles Example:** + +```xml + + + USal_confinement_500m + + + 500 + + + + + + + + + + + + + + + + + + + + + + + USal_confinement_500m + analyses\confinements\confinement_01\USal_Confinement_500m.shp + + 500 + + + + + + + + + + analyses\river_styles\manual_crosschecks\manual_crosscheck_01\USal_River_Styles.shp + + + + + + +``` + + + +**VBET Example**: + +```xml + + + + My realization Name + + + Hello + I did a thing and then another thing... + + + + 250 + 25 + 500 + 150 + 25 + 8 + 5 + 7 + 12 + 150 + 30000 + 30000 + + + + + + + + + + + + Large Buffer + 01_Inputs/02_Network/Network_001/Buffers/lg_buf1.shp + + + Medium Buffer + 01_Inputs/02_Network/Network_001/Buffers/med_buf1.shp + + + Small Buffer + 01_Inputs/02_Network/Network_001/Buffers/sm_buf1.shp + + + + + + + + My First Analysis + + + + Raw Valley Bottom + 02_Analyses/Output_001/Tucannon_VBET_unedited.shp + + + + Edited Valley Bottom + 02_Analyses/Output_001/Tucannon_VBET_edited.shp + + + + + + +``` + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/index.md new file mode 100644 index 0000000..212c4a5 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/index.md @@ -0,0 +1,117 @@ +--- +title: Riverscapes Projects +weight: 3 +--- +## The Problem +One of the most significant barriers to effective collaboration and leveraging of past work is being able to access and share any tool or model output or analysis, within the transparent context of the inputs and methods from which it was produced (Wilkinson et al. 2016). "Just send me the data", is rarely actually that simple. Plus, one of the hallmarks of scientific rigor is *reproducibility*. + +### Sharing is Expected... and Easier Today +Sharing used to be techncially difficult, but today is easy. Many great tools now exist for sharing data (typically as a zip file) to comply with open access and data sharing requirements: + + +However, it can be difficult to use those platforms to make **riverscapes specific** data more easily consumable, explorable and useful to your audiences. Especially given the complexity of so many riverscapes tools and workflows, "can you make the data available?" is an easy thing to coply with by uploading a zip file to one of the services above, but a very difficult thing to do properly. **We assert the Riverscapes community desperately needs data standards and simple tools for more effective sharing of riverscapes-specific data** ([Fryirs et al. 2019](http://dx.doi.org/10.1002/wat2.1372)). + +
+ +
+ +In an era of "big data", it is easy to get overwhelmed without appropriate context. Unfortunately, context means metadata, and very few researchers and practitioners have the time or are likely to produce that metadata manually. However, failure to do so contributes to "dark knowledge" (censu [Jeschke et al. 2019](https://dx.doi.org/10.1139/facets-2019-0007)) through *inaccessible data and information*, and we *can* do better. We need to better leverage each other's work, but we often do not because it is takes too much time. + +## A Better way for the Riverscapes Community + +
+
+
+
+

GOALS

+ +
    +
  1. Make it easier to produce, curate and organize riverscapes analyses in the context of the inputs and intermediates they were produced from. - i.e. make exploreable in RAVE
    2. +
  2. Foster transparency, reproducibility and sharing of riverscapes data and analyses.
    3. +
  3. Simplify ability for tool users to make tool outputs F-A-I-R or at least F-A-R
    4. +
+
+
+
+ +
+To achieve the above goals, we propose packaging data as **riverscapes projects** . This helps both the developer and the tool user grow their audiences for their tools + +One way of achieve the third goal of packaging analyses as **riverscapes projects** is to facilitate the contribution of Riverscapes Data to a [**DATA** Warehouses](/Data_Warehouses) for sharing and achieve **F**-**A**-**I**-**R**. With our [RAVE tools](https://rave.riverscapes.xyz) and [Warehouse](](/Data_Warehouses) ) we strive to make it easy to contribute your data as a riverscapes project , which are: +- [**F**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-2)indable, +- [**A**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-3)ccessible, and +- *ideally* [**I**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-4)nteroperable and +- [**R**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-5)e-useable. + +There are many other platforms and warehouses where full or partial **F**-**A**-**I**-**R** can be achieved (e.g. [zeondo](https://zenodo.org/), [HydroShare](https://www.hydroshare.org/), [FigShare](https://figshare.com/) or [OpenAIRE](https://openaire.com/)). These systems will not necessarily have awareness of what a **riverscapes projects** is, but they can handle uploading the data as a zip file, and at least the F, A and R parts of FAIR. + +Note the **F**-**A**-**I**-**R**, correspond to the **f**indable, **a**ccessible, **i**nteroperable and **r**e-useable [Principles](https://force11.org/info/the-fair-data-principles/) (Wilkinson et al. [2016](https://www.nature.com/articles/sdata201618)), which the RC strives towards and helps facilitate the riverscapes community follow. + + + + +## Riverscapes Projects + +We developed a data standard for packaging up riverscapes analyses (i.e. outputs of any [RC compliant tool](/Tools) into **riverscapes projects** . The project data can be navigated through a project tree like shown at right. + +[Riverscapes-compliant tools](/Tools) automatically produce datasets that we call "projects". Each project is accompanied by metadata documentation in the form of an [XML project file](/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.html). These project files have specific requirements and must comply with the [riverscapes project schema](/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Program/). In addition, the projects have a simple, standardized folder structure in which all data files are saved and or modified to disc (I/O). + +Riverscape projects can also be manually produced for any dataset and analysis to provide it context. For datasets that you want to share with a large audience, but may not produce that many times, it still may be worth the investment. + + + +### Overview Illustrated + +This five minute video explains the basics of riverscapes projects. + +
+ +
+ + + +## What are the Benefits of Riverscapes Projects? +Beyond better organization and transparency, the major benefits of riverscapes projects are: +- [Easy Visualization & Exploration in GIS & Web](#easy-visualization-and-exploration-in-gis-and-web) +- [Easier to Share with Metadata](#easier-to-share-with-metadata) +- [Scalable Analyses & Interoperable](#scalable-analysis--interoperability) with other Riverscapes Compliant Tools + + +### Easy Visualization and Exploration in GIS and Web +Sharing and opening any project in the [RV](http://rave.riverscapes.net/) (Riverscapes Viewer). You can reach GIS audiences with RV in ArcGIS or QGIS, or non-GIS users through WebRV. +
+ +
Example of WebRV view of a project. You can curate "Views" of collections of layers in your project, or they can add any layer to the map and see it symbolized as you intended it to be visualized. As the curator of your own project type, you can specify this symbology consistently. +
+ +- Helps you achieve [**A**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-3)ccessiblity and [**R**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-5)e-useability principles. + + +### Easier to Share with Metadata +
+ +
All layers have easily viewed Metadata from the Project Tree, which allows tracing back individual layers to their original sources or externally referenced projects. +
+ The packaging of data into a folder or zip file that can be easily shared, and then opened in any [RV app](http://rave.riverscapes.net) is handy. It ensures that your audience will see the data organized as you want it to be, with the right context, and correct symbology. + +Riverscapes projects can be stored in [Riverscapes Warehouses](/Data_Warehouses) and made publicly available. - *Riverscapes projects in a warehouse can be discovered through websites, webGIS maps, APIs, web mapping tile services (e.g. WMS or WMST).* + +Moreover, Riverscapes Projects facilitate automated metadata production and housekeeping. An example of the automatically generated metadata for a [production-grade, network tool](http://tools.riverscapes.net) is shown at left. + +- Helps you achieve [**F**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-2)indability, [**A**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-3)ccessibility, and [**R**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-5)e-useability principles. + +### Scalable Analysis & Interoperability +Riverscapes projects can be accessed, modified and populated with cloud computing because querying, and batching operations are possible with a consistent data standard and storage. Plus, other riverscape-compliant projects can easily reference each other. + +- Helps you achieve [**I**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-4)nteroperability and [**R**](https://force11.org/info/the-fair-data-principles/#elementor-toc__heading-anchor-5)e-useability principles. + +----------- + +## References +- Fryirs KA, Wheaton JM, Bizzi S, Williams R, Brierley GJ. 2019. To plug-in or not to plug-in? Geomorphic analysis of rivers using the River Styles Framework in an era of big data acquisition and automation. Wiley Interdisciplinary Reviews: Water 6 : e1372. DOI: [10.1002/wat2.1372](http://dx.doi.org/10.1002/wat2.1372) +- Jeschke JM, Lokatis S, Bartram I, Tockner K. 2019. Knowledge in the dark: scientific challenges and ways forward. FACETS. DOI: [10.1139/facets-2019-0007](https://dx.doi.org/10.1139/facets-2019-0007) +- Wilkinson MD et al. 2016. The FAIR Guiding Principles for scientific data management and stewardship. Scientific Data 3 : 160018. DOI: [10.1038/sdata.2016.18](http://dx.doi.org/10.1038/sdata.2016.18) diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/xml_validation.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/xml_validation.md new file mode 100644 index 0000000..e4fa293 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/xml_validation.md @@ -0,0 +1,67 @@ +--- +title: XML Validation +--- + +Riverscapes relies on several different [Extensible Markup Language](https://en.wikipedia.org/wiki/XML) (XML) files. They are used to define the individual projects, the data warehouses that store these projects and also how the projects are displayed in [RAVE](http://rave.riverscapes.net/). + +Each of these types of XML has a different set of rules that define the tag names, attributes and how these are laid out in the file. These rules are defined in a [XSD schema files](https://en.wikipedia.org/wiki/XML_schema) that are available online. + +Whenever writing XML by hand or, more likely, writing code to do so, it is absolutely vital that the XML produced is validated against the XSD schema file to check for errors and omissions. This process will verify that all tag names are valid, that the required tags are present and that the nesting of all the tags meets the XSD rules. + +There are lots of tools available for validating XML. Indeed, most modern Integrated Development Environments (IDE) software can perform this task. There are even online validation tools, although they tend rely on the files being uploaded and so they only tend work on one file at a time. + +Our preferred tool for validating XML is Microsoft's free [Visual Studio Code](https://code.visualstudio.com/). The following instructions describe how to configure and perform XML validation using Visual Studio Code. A [video description](#video-demonstration) at the bottom of this page demonstrates these steps. + +# Prerequisites + +1. [Visual Studio Code](https://code.visualstudio.com/). +1. [Java Development Kit](https://developers.redhat.com/products/openjdk/download?sc_cid=701f2000000RWTnAAO) (JDK). On Windows it's recommended that you download and use the MSI installer to walk through the installation. At the time of writing the `jdk-8u252-x64` MSI is the most appropriate download. +1. Install Red Hat XML Tools in Visual Studio Code: + 1. Open Visual Studio Code. + 1. Switch to the extension Marketplace (5th icon down the left side). + 1. Search for "Red Hat XML Tools". + 1. Click Install. + 1. Close and restart Visual Studio Code. + +# Which XSD To Use: + +Use the following URLs in the `namespaceSchemaLocation` attribute in the root level node of your XML: + +|XML Type|XSD URL| +|---|---| +|[Riverscapes Project XML Files]({{ site.baseurl}}/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/Project/projectxml.html)|[https://raw.githubusercontent.com/Riverscapes/Program/master/Project/XSD/V1/Project.xsd](https://raw.githubusercontent.com/Riverscapes/Program/master/Project/XSD/V1/Project.xsd)| +|[RAVE Business Logic XML](http://rave.riverscapes.net/business-logic.html)|[https://raw.githubusercontent.com/Riverscapes/RaveAddIn/master/RaveAddIn/XML/XSD/project_explorer.xsd](https://raw.githubusercontent.com/Riverscapes/RaveAddIn/master/RaveAddIn/XML/XSD/project_explorer.xsd)| + +# XML Validation + +Open the XML file that you want to validate. Ensure that the XML file refers to a schema namespace in the root XML tag of the file. Here's an example from the top of a riverscapes project file referring to the [XSD file online in the GitHub repository](https://github.com/NorthArrowResearch/riverscapes-programs/blob/master/Projects/BRAT/XSD/V1/Project.xsd). The namespace reference is on line 3: + +```xml + + + Riverscapes Context for HUC 17120007 + RSContext + 3f286d71-6191-4f5b-a6fc-468759e7f18eeeb79d24-68b5-405a-be55-8e23fdf929dcAnabranch + 1.0.0 + 2020-05-06T12:29:43.807018 + 2020-05-06T12:29:43.817540 + 17120007 + Warner Lakes + + +... +``` + +Open the terminal pane (CTRL+J on Windows) and switch to the "Problems" tab. Any problems with the XML should be underlined in red and also appear in this Problems pane. Test that validation is working by writing some invalid XML (either a nonsense tag name or deleting an angle bracket etc.). + +# Helpful Features + +1. When typing XML tags use intellisense (CTRL+Space) to suggest valid tags and attributes. +1. Right click anywhere in the XML file to "reformat" the document. This will reindent the nested tags. + +# Video Demonstration + +
+ +
\ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Source_Code/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Source_Code/index.md new file mode 100644 index 0000000..7290117 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/Source_Code/index.md @@ -0,0 +1,70 @@ +--- +title: Source Code Documentation +weight: 1 +--- + +Riverscapes tools are public and intended to be used by a broad variety of users. Therefore it is vital that the source code is logically organized and well documented. + +Riverscapes tool source code is hosted using the free and public [GitHub]() service. Generally speaking, each tool source code resides in its own git repository. These repositories are collected within a Riverscapes [organization on GitHub](https://github.com/orgs/Riverscapes/dashboard). Contact [North Arrow Research](mailto:info@northarrowresearch.com) should you wish to have your tool included within this Riverscapes organization. + +The following guidelines are intended for riverscapes tool developers to consistency and thoroughly document their source code. + +## Source Code Check List + +Here are some things to remember before uploading your source code onto the internet. Review **all** the files in **all** the folders in your source code directory and: + +* Ensure that all the files needed to run the source code are in the repo! The best way to confirm this is to copy the source code onto a separate computer that has never had the source code on it before and then try and run the code there. Guaranteed the first time you do this it will not work and you will realize that you've forgotten to include one or more files. External dependencies don't need to go in your repo, but any file that you've authored should be included. +* Delete any temporary files or files that are no longer needed. +* Remove all sensitive information such as user names and passwords. It's best that your code reads these from a configuration file that is separate from your source code. This configuration file can then be excluded from your repo using a [.gitignore](https://help.github.com/articles/ignoring-files/) file. If you do this, then it can be helpful to create another file called something like `config.TEMPLATE`, with the exact same structure as your configure file, but without the sensitive information, and then include this in the repo. Others trying to use your code can use this template as a starting point. +* Remove all references to local file or folder paths. Any such references should be passed to your tool as command line parameters and not as literals in code files. See video below. +* Avoid putting binary files in your repo (databases, DLLs, compiled items etc). Again, use a [.gitignore](https://help.github.com/articles/ignoring-files/) file to exclude these. + +
+
+ + +## Source code in Riverscapes GitHub + +Your source code should be stored in a git repository and uploaded into the [Riverscapes ](https://github.com/orgs/Riverscapes/dashboard) organization on GitHub. If you're new to GitHub, the default is to upload repositories under the umbrella of your own user account, so it's important that you understand how to upload the repo under the riverscapes organization. + +You should learn and understand how to use [git](https://git-scm.com/) first! Certainly research any of the terms below that are not readily obvious to you. But, at a high level, starting from a folder of non-version controlled source code on your computer, the steps are: + +1. Install git version control software. +2. Initialize a new git repo in your top level source code folder. +3. Commit all changes to the git repo. +4. Login to [GitHub](http://github.com) +5. Navigate to the [Riverscapes organization](https://github.com/orgs/Riverscapes/dashboard). +6. Click the green **New Repository** Button and fill in the necessary fields. +7. Copy the SSH address that GitHub provides once the repo is created. +8. On your local system, add a new **Remote**. Call it `origin` and paste the SSH address. +9. Push your source code up to origin. +10. Refresh the repo page on GitHub and verify that your source code appears. + +[Git](https://git-scm.com/) is natively a command line tool that many developers struggle to master. While most git operations can be performed from dirctly within the GitHub web interface. However there are several excellent user-interface driven software products that simplify git operations and make it less intimidating to learn. Some of our favourites are: + +* [Git Kraken](https://www.gitkraken.com/) +* [Source Tree](https://www.sourcetreeapp.com/) +* [GitHub Desktop Client](https://desktop.github.com/) + + +## Tag your releases + +Review the commit history and create git [tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) at each official release using a systematic numbering system. Remember to **push** your tags to origin (or they will only reside on your local git repo). + + + +## Read Me File + +Add a file to the top level folder of your repo called `readme.md` The `md` suffix tells GitHub that this is a plain text [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) document. It's important because GitHub renders this readme file below the listing of source code. See the [bottom of the PyBRAT repo](https://github.com/Riverscapes/pyBRAT) for an example. + +Learn [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) if you don't know it already. You're going to be writing a lot of it! + +For now, simply put one or two sentences in the read me that provide a high level overview of your model. You will be adding more information to this file later... + +## License File + +Create and a plain text file in the root of your repository simply called `LICENSE` (no file suffix). [Choose an appropriate license](https://choosealicense.com/) and put the text in this file. Most Riverscapes models use the [GNU 3.0 license](https://www.gnu.org/licenses/gpl-3.0.en.html). + +## Documentation Web Site + +Each tool should have its own documentation web site that explains how the tool works as well as how to obtain, install and run the tool itself. See the separate section on [Riverscapes Tool Web Sites]({{ site.baseurl}}/Technical_Reference/Documentation_Standards/WebSites/) for more information. Any peer-reviewed publications that vet the methods implemented in the tool or code should be cited. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Common.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Common.md new file mode 100644 index 0000000..a46151a --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Common.md @@ -0,0 +1,245 @@ +--- +title: Common Content +weight: 4 +--- + +## Some Common Components of Pages + +These days, there are many websites that allow you to create content (e.g. videos, tweets, spreadsheet, etc.) and embed it in your website. The git hosted web pages we use are written in markdown, but can recognize blocks of html like ` + + +Note using the `
` tags around your ` + +``` +Instead of: +``` html + +``` +#### Markdown Alternative +However, for regular markdown there is still an option that includes a preview of the site (this is supported, for example in GitHub issue forums, whereas the iframe is not). It relies on the thumbnails that YouTube automatically generates for every youtube vide on its image server (`https://img.youtube.com/`; see [here](https://www.sitepoint.com/youtube-video-thumbnail-urls/) for more information on how YouTube does this). Thus, if you use the image markdown syntax (`![alt-text](imagepath)`) inside a regular markdown hyperlink (`[text](url)`) you can produce the illusion of an embedded youtube video (it is actually just an image that links to YouTube). + +Use the following syntax and substitute in your YouTube video ID for `YTID`: +``` markdown +[![Alt-text](https://img.youtube.com/vi/YTID/0.jpg)](https://www.youtu.be/watch?v=YTID) +``` +For example, using the above id of `4UKe5BkzJEY` for `YTID` would show up as:
+[![Alt-text](https://img.youtube.com/vi/4UKe5BkzJEY/0.jpg)](https://www.youtu.be/watch?v=4UKe5BkzJEY) + +Note subsituting `1.jpg` for `0.jpg` switches to a thumbnail size.
+[![Alt-text](https://img.youtube.com/vi/4UKe5BkzJEY/1.jpg)](https://www.youtu.be/watch?v=4UKe5BkzJEY) + +Finally, if you want to make the hyperlink open in a new tab, use: +``` markdown +[![Alt-text](https://img.youtube.com/vi/YTID/0.jpg)](https://www.youtu.be/watch?v=YTID){:target="_blank"} +``` + +------ +### Embedding an Image +Of all the things to do in these markdown Git-hosted webpages, embedding an image is actually the most annoying and difficult (compared with WYSWYG web platforms like Weebly or Google Sites). The reasons are it is not a drag and drop operation and you kind of need to know what you are doing. The steps are: +1. Get your image prepared. +2. Resize your image to desired size that it will appear on page (e.g. width of 300 pixels would be half width, 600 pixels would be fuller). You can use Photoshop or [Faststone Capture](http://www.faststone.org/FSCaptureDetail.htm) (for example). +3. It is best practice to then tinify (make smaller) your image using something like [TinyPng](https://tinypng.com/). These typically achieve 20 to 50% compression and help your images and whole page load faster. +4. Copy your image to the appropriate folder path (for BRAT, that is [`\docs\assets\images\`](https://github.com/Riverscapes/pyBRAT/tree/master/docs/assets/images) or subfolder and will be referred to by path as `"/images/"`) +5. Reference the image in your markdown page. This is done with following syntax for the [`BRAT_Logo-wGrayTxt.png`](https://github.com/Riverscapes/pyBRAT/blob/master/docs/assets/images/BRAT_Logo-wGrayTxt.png): + +``` markdown +![BRAT_Logo-wGrayTxt](\assets\images\BRAT_Logo-wGrayTxt.png) +``` + +And will look like: + +![BRAT_Logo-wGrayTxt](\assets\images\BRAT_Logo-wGrayTxt.png) + +To make that image hyperlinkable (clickable), you enclose it in square brackets `[]` and then put hyperlink in `()` parentheses. For example, to make image above clickable and linking to [http://google.com](http://google.com) + +``` markdown +[![BRAT_Logo-wGrayTxt](\assets\images\BRAT_Logo-wGrayTxt.png)](http://google.com) +``` +In this video, I illustrate how to do steps 2-5 of this with a screen shot taken in Faststone Capture: + +
+ +
+ +------ +### Adding a Button + +The best places to look for examples of buttons is on the [styleguide template](https://riverscapes.github.io/TemplateDocs/styleguide.html) - and [corresponding markdown](https://github.com/Riverscapes/TemplateDocs/edit/master/styleguide.md) or to copy a button you like from an existing page. Buttons can be: +- Just text: Back to BRAT Home +- Image and Text: Back to BRAT Home +- or Icon and Text: Back to ETAL Standards + +See [Icon Library](https://fontawesome.com/v4.7.0/icons/) for a list of icons that our Riverscapes recognize and you can use. + +The basic syntax for a button goes something like: +``` markdown + Back to ETAL Standards +``` + +In the video below, we walk you through how to make your own button to navigate to a specific page on the website Back to ETAL Standards and an external URL (http://google.com) Take me Away to Google. + +
+ +
+------ +### Embed a Slideshow + +Its nice to be able to embed slideshows on a page: + +
+ +
+ +This video walks you through how to: + +
+ +
+ +------ +### Linking to a PDF + +#### Providing a useful citation with links + +There are many ways to provide a citation. This is the _least useful_: + +- Macfarlane WW, Gilbert JT, Gilbert JD, Saunders WC, Hough-Snee N, Hafen C, Wheaton JM and Bennett SN. 2018. What are the Conditions of Riparian Ecosystems? Identifying Impaired Floodplain Ecosystems across the Western U.S. Using the Riparian Condition Assessment (RCA) Tool. Environmental Management. DOI: 10.1007/s00267-018-1061-2. + +This is _better_ because it provides a link from the title to the Research Gate entry (which tracks statistics on reads and downlaods), and link from the DOI to the stable, pemenant URL: + +- Macfarlane WW, Gilbert JT, Gilbert JD, Saunders WC, Hough-Snee N, Hafen C, Wheaton JM and Bennett SN. 2018. [What are the Conditions of Riparian Ecosystems? Identifying Impaired Floodplain Ecosystems across the Western U.S. Using the Riparian Condition Assessment (RCA) Tool](https://www.researchgate.net/publication/325098563_What_are_the_Conditions_of_Riparian_Ecosystems_Identifying_Impaired_Floodplain_Ecosystems_across_the_Western_US_Using_the_Riparian_Condition_Assessment_RCA_Tool). Environmental Management. DOI: [10.1007/s00267-018-1061-2](http://dx.doi.org/10.1007/s00267-018-1061-2). + +** This is our lab standard for citations ** -_link to ResearchGate through title, link to DOI through DOI._ + +If you need some help on how to upload your content to ResearchGate, see here: + +
+ +
+ + + + +#### Hosting a PDF on AWS instead of ResearchGate + +There are situations where its nice to provide a direct link to the PDF (e.g. slides in workshop or handout), that we don't want to post on ResearchGate. If we want to provide a link to a PDF that we hosted on AWS, here's an example: + +- [PDF of my paper](https://s3-us-west-2.amazonaws.com/etalweb.joewheaton.org/Workshops/BRAT/2018/Burnt/Macfarlane_et_al-2018-Environmental_Management.pdf) + +The syntax for above is: `[PDF of my paper](https://s3-us-west-2.amazonaws.com/etalweb.joewheaton.org/Workshops/BRAT/2018/Burnt/Macfarlane_et_al-2018-Environmental_Management.pdf)` + +The video (scroll down) shows how to upload to [AWS](http://aws.amazon.com) (easy). + +If I want to show a PDF icon next to above citation, to indicate there is a pdf, I can use my pdf [icon](https://fontawesome.com/v4.7.0/icon/file-pdf-o) with ``: + +- Macfarlane WW, Gilbert JT, Gilbert JD, Saunders WC, Hough-Snee N, Hafen C, Wheaton JM and Bennett SN. 2018. [What are the Conditions of Riparian Ecosystems? Identifying Impaired Floodplain Ecosystems across the Western U.S. Using the Riparian Condition Assessment (RCA) Tool](https://www.researchgate.net/publication/325098563_What_are_the_Conditions_of_Riparian_Ecosystems_Identifying_Impaired_Floodplain_Ecosystems_across_the_Western_US_Using_the_Riparian_Condition_Assessment_RCA_Tool). Environmental Management. DOI: [10.1007/s00267-018-1061-2](http://dx.doi.org/10.1007/s00267-018-1061-2). + +But, that doesn't allow me to click on PDF icon and get to it. To do this, I need to have a html `` tag: + +- Macfarlane WW, Gilbert JT, Gilbert JD, Saunders WC, Hough-Snee N, Hafen C, Wheaton JM and Bennett SN. 2018. [What are the Conditions of Riparian Ecosystems? Identifying Impaired Floodplain Ecosystems across the Western U.S. Using the Riparian Condition Assessment (RCA) Tool](https://www.researchgate.net/publication/325098563_What_are_the_Conditions_of_Riparian_Ecosystems_Identifying_Impaired_Floodplain_Ecosystems_across_the_Western_US_Using_the_Riparian_Condition_Assessment_RCA_Tool). Environmental Management. DOI: [10.1007/s00267-018-1061-2](http://dx.doi.org/10.1007/s00267-018-1061-2). + +This was done with `` and collapsing the PDF icon inside the hyperlink `` tag. + +##### Or a Button... + +Finally, a button can be nice for the paper. + + Download my PDF please! + + +A long-winded video showing how you do all the above, plus the upload to AWS. + +
+ +
+ +------- + +## Embed a Gist + +If I have a GIST (e.g. [this one](https://gist.github.com/joewheaton/002acd9ea725f6d4a1bac38ee9a0dd50)), you can simply copy the embed code and paste it in. For example, this produces: +`` this: + + + + +----- + +## Add a Google Search Bar for your Site + +If you want a Google Search Bar for your site, use Google's [Programmable Search Engine](https://programmablesearchengine.google.com/controlpanel/all). You have to Add your search engine, and in it tell it `what site() to search?` (e.g. for GCD it might be `gcd/riverscapes.net/*`) + +It then gives you some code (e.g.): +``` + +
+``` +that correspondes to a search bar: + +
+ +You can customize the look and feel as well. + +----- +## Add a DOI with Zenodo for your Website or Tool + +[Zedondo](https://zenodo.org/) provides an easy way to make your website citeable, trackable and indexed. You can even make your contribution part of the [Riverscape Consortium Zeondo Community]() + +1. Create a Zenodo account (preferably linked you your [ORCID](https://orcid.org)) +2. Link your GitHub account in your profile. +3. Click on GitHub in your settings. You will have access to all your repositories. +4. Flip the switch to enable Zenodo tracking of your repository. Do this before creating a release. +5. Create a release (once tracking, Zenodo will automatically download a .zip-ball of each new release and register a DOI.) +6. Get your badge! + +For example, for the [Low-Tech PBR website](http://lowtechpbr.restoration.usu.edu), it generated this badge: [![DOI](https://zenodo.org/badge/156031626.svg)](https://zenodo.org/badge/latestdoi/156031626) and provided the following markdown: + +``` +[![DOI](https://zenodo.org/badge/156031626.svg)](https://zenodo.org/badge/latestdoi/156031626) +``` + +The Zeondo Entry also then provides a suggested citation! We've been adding these to our site `footer.html`. For example for GCD we used: + +``` +
+ To cite content from this site use:
DOI + +
+ +
+ The GCD site is licensed under a GNU General Public License v3.0,
and some specific content is licensed with + + Picture + +
  +
+``` +
+ To cite content from this site use:
DOI + +
+ +
+ The GCD site is licensed under a GNU General Public License v3.0,
and some specific content is licensed with + + Picture + +
  +
\ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Consistency.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Consistency.md new file mode 100644 index 0000000..37b9008 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/Consistency.md @@ -0,0 +1,64 @@ +--- +title: Consistency & Utility +weight: 5 +--- + +## Making your documentation consistent + +Always attempt to follow the template set by previous pages in the same parent folders (e.g. if writing a [command page](/Documentation/Commands/) ). + +### Making your documentation useful with hyperlinks + +Poorly cross-referenced webpages (especially those on documented) are just annoying and a missed opportunity. Empathize with your audience enough to make sure they can find whatever you talk about. + +So an example would be to mention that we have good ETAL BRAT Standards, but fail to link you to that page. + +#### Example 1 - No references +_How its rendered:_ +We have good ETAL BRAT Standards. + +_How its written in markdown:_ +``` markdown +We have good ETAL BRAT Standards. +``` + +_Annoying: without references this is vague._ + +#### Example 2 - Amateur hyperlink listed but not linked +_How its rendered:_ We have good ETAL BRAT Standards (http://brat.riverscapes.net/Documentation/Standards/). + +_How its written in markdown:_ +``` markdown +We have good ETAL BRAT Standards (http://brat.riverscapes.net/Documentation/Standards/). +``` + +_Annoying: as a user can't even click on this, they need to copy and paste it into their browser ._ + +#### Example 3 - Amateur hyperlink listed and linked +_How its rendered:_ We have good ETAL BRAT Standards ([http://brat.riverscapes.net/Documentation/Standards/](http://brat.riverscapes.net/Documentation/Standards/)). + +_How its written in markdown:_ +``` markdown +We have good ETAL BRAT Standards ([http://brat.riverscapes.net/Documentation/Standards/](http://brat.riverscapes.net/Documentation/Standards/)). +``` + +_Amateurish: do we need to list the URL out?._ + +#### Example 4 - hyperlink only - preferred +_How its rendered:_ +We have good [ETAL BRAT Standards](http://brat.riverscapes.net/Documentation/Standards/). + +_How its written in markdown:_ +``` markdown +We have good ETAL BRAT Standards We have good [ETAL BRAT Standards](http://brat.riverscapes.net/Documentation/Standards/). +``` + +_Our default standard._ + + +------ + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.md new file mode 100644 index 0000000..49fb1a9 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.md @@ -0,0 +1,100 @@ +--- +title: Riverscapes Report Card Template +weight: 1 +--- + + + + +TRL Grade - Needs to be updated to correct TRL grade 1-7 +Tool Logo TOOL X is _description/definition_. This report card communicates TOOL X's compliance with the Riverscape Consortium's published [tool standards](https://riverscapes.net/Tools). + +# Report Card Summary + +| Tool | [NAME OF TOOL](https://toolurl.riverscapes.net) | +| Version | [0.0.00](https://github.com/Riverscapes/tool/releases/tag/0.0.0) | +| Date | YEAR-MM-DD | +| Assessment Team | Names and/or Links | +| Current Assessment | ![research](https://raw.githubusercontent.com/Riverscapes/riverscapes-website/master/assets/images/tools/grade/TRL_4_32p.png) [Research Grade](https://riverscapes.net/Tools/discrimination.html#tool-grade) | +| Target Status | ![professional](https://raw.githubusercontent.com/Riverscapes/riverscapes-website/master/assets/images/tools/grade/TRL_5_32p.png) Professional Grade | +| Riverscapes Compliance | ![Riverscapes Compliant](https://riverscapes.net/assets/images/rc/RiverscapesCompliant_32.png) [Riverscapes Compliant](https://riverscapes.net/Tools/#riverscapes-compliant-tools) | +| Assessment Rationale | 1-3 Sentence Summary by reviewers justifying assessment determination and summarizing from details below. | + + + +# Report Card Details + +This tool's [discrimination](https://riverscapes.net/Tools/discrimination#model-discrimination) evaluation by the [Riverscapes Consortium's](https://riverscapes.net) is: + +**Evaluation Key:** +None or Not Applicable: • +Minimal or In Progress: • +Functional: • +Fully Developed: + +| Criteria | Value | Evaluation | Comments and/or Recommendations | +|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| :----------------------------- | :----------------------------- | | :----------------------------- | +| [Tool Interface(s)](/Tools/discrimination.html#interface) | : ArcGIS 10.x AddIn, Stand Alone Windows Tool | | Comments | +| Scale | Reach (cell scale resolution, reach scale extent) | | Comments. | +| Language(s) and Dependencies | *e.g.* C# | | Comments. | +| Vetted in Peer-Reviewed Literature | Yes. [Doe et al. (2015)]() | | Comments. | +| Source Code Documentation | Desc. | | Comments. | +| Open Source | [open-source](https://github.com/Riverscapes/gcd) with [GNU General Public License v 3.0](https://github.com/Riverscapes/gcd/blob/master/LICENSE) | | Comments. | +| Tool and Source Code Citable | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7248344.svg)](https://doi.org/10.5281/zenodo.7248344) | | *Provide citation, e.g.* Phlip Bailey, Joseph Wheaton, Matt Reimer, & James Brasington. (2020). Geomorphic Change Detection Software (7.5.0). Zenodo. DOI: [10.5281/zenodo.7248344](https://doi.org/10.5281/zenodo.7248344) | +| User Documentation | [Link(s)]() | | Comments. | +| Easy User Interface | Desc. | | Comments. | +| Scalability | Desc. | | Comments. | +| Produces [Riverscapes Projects](/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/) | Tool is outputting to disk data in a Riverscapes Project that can be opened in [RV](http://rave.riverscapes.net). | | Comments. | + +## F-A-I-R Assessment + + **F**-**A**-**I**-**R**, corresponds to the **f**indable, **a**ccessible, **i**nteroperable and **r**e-useable [Principles](https://force11.org/info/the-fair-data-principles/) (Wilkinson et al. [2016](https://www.nature.com/articles/sdata201618)), which the RC strives to follow and to help facilitate making it easier for the riverscapes community to follow. **F**-**A**-**I**-**R** can apply to metadata, data and the tool itself. + + + + +| FAIR Principle | Value | Evaluation | Comments | +| ----------------- | ----- | ------------------------------------------------------ | --------- | +| **METADATA** | | | | +| **F**indable | Desc. | | Comments. | +| **A**vailable | Desc. | | Comments. | +| **I**nteroperable | Desc. | | Comments. | +| **R**e-useable | Desc. | | Comments. | +| **DATA** | | | | +| **F**indable | Desc. | | Comments. | +| **A**vailable | Desc. | | Comments. | +| **I**nteroperable | Desc. | | Comments. | +| **R**e-useable | Desc. | | Comments. | +| **TOOL** | | | | +| **F**indable | Desc. | | Comments. | +| **A**vailable | Desc. | | Comments. | +| **I**nteroperable | Desc. | | Comments. | +| **R**e-useable | Desc. | | Comments. | + +Overall summary of tool **FAIR**-ness : Tool evaluation summary. + +## Tool Output Utility + +All Riverscapes tools package up data in Riverscapes Projects. This section evaluates the utility of those outputs to end-users that are not running the tool, but instead leveraging its outputs. + +| Criteria | Value | Evaluation | Comments | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------------------------------------------------------|--------------------------------| +| :----------------------------- | :----------------------------- | :----------------------------- | :----------------------------- | +| [RV](https://rave.riverscapes.net)- Compliant Riverscapes Projects ? | Desc. | | Comments. | +| [RV](https://rave.riverscapes.net) Business Logic Defined? | Desc. | | Comments. | +| Riverscapes Projects hosted in public-facing [Riverscapes Warehouse(s)](https://riverscapes.net/Data_Warehouses/#warehouse-explorer-concept) | Desc. | | Comments. | +| Riverscapes Projects connected to [Web-Maps](https://riverscapes.net/Data_Warehouses#web-maps) | Desc. | | Comments. | +| Riverscapes Projects connected to Field [Apps](https://riverscapes.net//Data_Warehouses#apps---pwas) | Desc. | | Comments. | + +## Developer Intent + +*Development team (not evaluation team) should provide 1-3 paragraphs and/or some bullets and/or figures describing where they hope to go in future releases.* + +If you share the above vision, get in touch with the developers to support/fund the effort. + +-------------------- + +The [Riverscapes Consortium's](https://riverscapes.net) Technical Committee provides report cards for tools either deemed as "[riverscapes-compliant](https://riverscapes.net/Tools/#riverscapes-compliant)" or "[pending riverscapes-compliance](https://riverscapes.net/Tools/#tools-pending-riverscapes-compliance)" . diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/index.md new file mode 100644 index 0000000..f80ab72 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/index.md @@ -0,0 +1,23 @@ +--- +title: Tool Report Card Instructions +--- + +See [here](/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.html) for a preview of a blank Tool Report Card Template. + +A copy of the markdown template can be dowloaded or copied [here](https://github.com/Riverscapes/riverscapes-website/blob/master/Tools/Technical_Reference/Documentation_Standards/WebSites/ReportCards/Tool_ReportCard_0-0-00.md?plain=1) + +Typically, the Technical Review Committee will be filling out this markdown and these instructions are for + +## Step 1 - Rename the file + +We recommend putting report cards (allows for multple versions) in a `About\Status\` subfolder located in the root of your website folder (e.g. `Docs`). Reviewers should provide a working version of the markdown to the GitHub source code as a review branch. Copy the template and then rename it from `Tool_ReportCard_0-0-00.md` to what ever version you are publishing (this should match your GitHub release). For example, if you are publishing a report card on version 1.2.1, it would become `Tool_ReportCard_1-2-01.md`. + +## Step 2 - Complete Review + +The review needs to updated to fill out the Value, Evaluation and Comment columns of each of the table. Multiple members of the Techncial Review Committee should indepently assess and then a lead reviewer will provide a rough draft to the others. Members should proof-read the review for typos and accuracy. + +## Step 3 - Submit Pull Request to Developer + +Once the review is completed, the lead reviewer should submit a pull-request, and assign the developer requesting the review, to review and approve the pull-request. + + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/bibliographies.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/bibliographies.md new file mode 100644 index 0000000..dda065c --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/bibliographies.md @@ -0,0 +1,62 @@ +--- +title: Automated Bibliographies +--- + +These instructions describe how to automate a bibliography within your website using the free [Zotero](https://www.zotero.org) bibliographic software. It is possible to maintain a private or shared library within Zotero and then use the Python script on this page to export the citations to a text file for inclusion in your web site. + +Riverscapes web sites are written as palin text markdown files, stored in git repositories and served over the internet using GitHub Pages. The script described in the following instructions will output a single, formatted markdown page containing all the citations for a single Zotero library. You can include this markdown page in your web site and GitHub Pages will generate the corresponding web page. Here's our [beaver restoration example](http://brat.riverscapes.net/references.html) that was generated using this script. + +## Step 1 - Prereqisites + +You will need a [Zotero](https://www.zotero.org) account with access to a library containing citations. You will also need [Python](https://www.python.org/) with [PIP](https://pypi.org/project/pip/) installed. + +## Step 2 - Zotero Configuration + +Login to your Zotero account online and click on the library that you want to include in your web site. It's a good idea to create a dedicated library for each citation listing that you want to generate. + +Note down the numeric portion of the library URL: + +![url]({{site.baseurl}}/assets/images/zotero/url_slug.png) + + Navigate to your Zotero account settings page (using the down arrow beside your account name). Switch to the `Feeds/API` tab and create a new API key. Keep this key private and somewhere safe, such as in a password manager. You are going to need it later in this process when you run the Python script. Be sure never to commit this key to git or somewhere that it could end up online. + +![settings]({{site.baseurl}}/assets/images/zotero/settings.png) + +## Step 3 - Create Script Workspace + +You will need a folder where you can save and run a Python script. This should **not** be inside your web site folder structure. Download and save the following Python script into this folder. + + + +## Step 3 Install Script Prerequisites + +Ensure that you have the [pyzotero](https://github.com/urschrei/pyzotero) Python library installed, by simply typing the following at the command line: + +`pip install pyzotero` + +Be sure to install pyzotero in the correct Python environment if you have more than one, or are using a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html). + +## Run the Python Script + +Open a command prompt and navigate to the folder where you saved the Python script earlier in this process. Type the following command: + +`python zotero.py LIBRARY_ID group|user YOUR_API_KEY BIBLIOGRAPHY_PATH` + +The LIBRARY_ID should be the numeric part of the zotero library URL noted down above. The next argument depends on whether your library is a personal **user** library or a **group** library shared among several people. Remove the one you aren't using. YOUR_API_KEY is the API key from the earlier step. And finally the BIBLIOGRAPHY_PATH is the location where you want the output bibliography to be generated. + +Note that the script generates an entirely new markdown file each time that it is run. It will **overwrite the existing file** if one exists. If you don't want this behaviour then edit the script to append the bibliography to the existing output markdown file. + +Type return to run the script. Review the markdown output before publishing. If you're publishing to a GitHub Pages web site (i.e. any riverscapes web site) then it's strongly recommended that you test your bibliography by [serving Jekyll locally]({{site.baseurl}}/Tools/Technical_Reference/Documentation_Standards/WebSites/testing_locally.html) before committing and pushing the output markdown file. + +You can tweak the output markdown as necessary. Just remember that each time you run the script it will overwrite your changes with the new markdown. This is especially important if you write any introductory text at the top of the file. Copy and paste it to a temporary location as a backup while you iterate running the script. + +## Script + + +## Video Demonstration + +
+ +
+ + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/creating_new_pages.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/creating_new_pages.md new file mode 100644 index 0000000..6f192d8 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/creating_new_pages.md @@ -0,0 +1,17 @@ +--- +title: Creating New Pages +weight: 1 +--- + +## Authoring New Content + +### Making a New File & Folder + +In this video, I show how to move existing files around on disc, create new folders, files and change the navigation, by simply manipulating file locations and the front matter of the mark down files. + + + + +### Understanding Automatic Sidebar Navigation, Naming & Ordering + +The Page Contents and [Site Contents](http://riverscapes.northarrowresearch.com/Technical_Reference/jekyll_toolbox.html#site-table-of-contents) are auto populated. Page contents are based on your use of headings (e.g. `## Heading 1, ### Heading 2, #### Heading 3...`) in your mark down. The Site Contents are based on the [front matter](http://riverscapes.northarrowresearch.com/Technical_Reference/jekyll_toolbox.html#front-matter) and [page sorting](http://riverscapes.northarrowresearch.com/Technical_Reference/jekyll_toolbox.html#page-sorting) you populate at top of your page. diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/edits.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/edits.md new file mode 100644 index 0000000..013cf64 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/edits.md @@ -0,0 +1,33 @@ +--- +title: Editing Existing Pages +weight: 2 +--- +## Edits + +### Making a Simple Edit in Browser +For simple edits to an existing Git-Hosted markdown page, you simply browse to the page in the [Code repository under `docs`](https://github.com/Riverscapes/pyBRAT/tree/master/docs), make edits, and then commit. See the example below: + + + + +### Making a More Complicated Edit Localy & Pushing Up + +You can use any text editor for editing markdown. [Typora](https://typora.io/) is a free text editor specifically for markdown that has the added advantage that it can render the code in the application so you can preview it. + +Below, I illustrate some edits using [Typora](https://typora.io/) and my favorite local GIT client, [GitKraken]( [Typora](https://typora.io/)). I also am using a local version of Jekyll and Linux ([see here for how](http://riverscapes.northarrowresearch.com/Technical_Reference/jekyll_toolbox.html#running-jekyll-locally)) so I can preview the changes in a web browser before uploading or committing them. + + + + + +### Spellchecking in Typora + +Always, spellcheck your markdown. In [Typora](https://typora.io/) that is simple: + + +------ + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/index.md new file mode 100644 index 0000000..31f5d3d --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/index.md @@ -0,0 +1,57 @@ +--- +title: Tool Web Sites +weight: 2 +--- + +Every riverscapes tool (piece of software) is documented using its own web site. These sites use a consistent design and content. They are intended to help end users discover, obtain and run the tools. The web sites are written as plain text [markdown](https://en.wikipedia.org/wiki/Markdown) files stored in a [GitHub](https://github.com/) repository. GitHub then handles serving these files as a web site. + +Tool developers can use the following material to learn how to write, test and publish tool web sites on GitHub. + +# Introduction - GitHub Pages + +GitHub can build a web site for your tool from simple text files stored in your repo! This is an excellent way to quickly and easily build a professional, polished documentation site for your tool that users can read to learn more about how it works. The beauty of this approach is that all you need to write are simple text files using the [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) syntax. No understanding of web technology is required! Here are a couple of examples: + +* [GCD](http://gcd.riverscapes.net) +* [PyBRAT](http://brat.riverscapes.net/) + + +# Creating a Web Site + +Here are the steps to create a documentation web site for your tool. GitHub also has lots of documentation online describing how to use this [GitHub Pages](https://pages.github.com/) technology. + +1. Download the [latest web template here](https://github.com/Riverscapes/riverscapes-jekyll-theme/releases/latest) from the riverscapes-jeklyll-theme +2. Unzip the file to the root of your repository. This will create a `docs` folder with the website template contained therein. Comit these changes (e.g. as `RS Website Template copied`) +3. If creating a website for a repository that is also your tool or sourcecode, skip ahead to step 4. If creating a repository that is just a website, move all contents of `docs` folder to root of repository and then delete `docs` folder. +4. Push your changes up to `origin` (i.e. the GitHub remote). +5. Open your repo home page on GitHub and: + 1. Click on the Settings link above the source code listing. + 2. Scroll down until you see **GitHub Pages** + 3. Choose **master branch /docs folder** in the source dropdown. + 4. Click **Save**. + 5. Wait 2-3 minutes for the site to get generated. + 6. Click on the link shown for your web site. Typically it will be of the form `http://riverscapes.github.io/YOURREPONAME` +5. [Create whatever other web pages](/Tools/Technical_Reference/Documentation_Standards/WebSites/creating_new_pages.html) you need and also store them in the docs folder. You will notice a bunch of suggested pages and templates you can either [edit](/Tools/Technical_Reference/Documentation_Standards/WebSites/edits.html) or delete. You can use folders to separate and group files. Note that the folder names are going to be interpreted into links on the web site. So do **not** use spaces in folder names. Instead use underscores in place of spaces, and do use capitalization. File names are not used as links, but the informal standard is to also avoid spaces and use all lower case for file names. + +You will need to wait 2-3 minutes after each push to GitHub for your site to be generated from your markdown documents. + +This short video shows how quick and easy the above is: +
+ +
+ + + +# Theming Your Site + +By default your web site will use a simple black and white theme. See the section on [theming]({{ site.baseurl}}/Tools/Technical_Reference/Documentation_Standards/WebSites/theming.html) that describes how to apply the standard riverscapes theme to your site. (i.e. the stylized theme used for this site.) + +# Site Content Recommendations + +It's recommended that - at an absolute minimum - you cover the following topics in your web site: + +* **Release Notes** - include a single page that lists each of the official releases, the date of the release, together with some high level description of the changes. Here's [an example](http://workbench.northarrowresearch.com/release_notes.html). +* **Acknowledgements** - content describing the contributors and funding sources. +* **Source Code** - link back to the GitHub repo so readers can easily obtain the source code should they need it. +* **Citations** - Either at the bottom of the home page, or on a dedicated page should more space be required. +* **Getting Started** - instructions on how users download, configure and run the code. +* **Prerequisites** - A list of dependencies required by users before the code will run, together with links and/or instructions on how to obtain them. This next point is incredibly important! It is often hard to know what technologies that you have on your computer are actually in use by your code. You should install your code on a *clean* computer that has never been used for development or had the source code on it to thoroughly understand what all is required. This is the only true way to understand what is required. Not doing this test will almost certainly mean that your instructions will be incomplete for some users that have a different computer configuration than you. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/styleguide.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/styleguide.md new file mode 100644 index 0000000..9896987 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/styleguide.md @@ -0,0 +1,329 @@ +--- +title: Style Guide Illustrated +weight: 8 +--- + +This page exists mainly for checking the CSS styles and as a reference for the markdown and html to produce particular content. All styles here are simply derived from [Foundation's core CSS classes](https://foundation.zurb.com/sites/docs/) + +The source code is provide in a `code block` above of the demonstrated feature. Alternatively, you can view the source code for this page [here](https://github.com/Riverscapes/Program/blob/master/docs/Technical_Reference/Documentation_Standards/WebSites/styleguide.md). + + +`# H1` produces: +# H1 + +***NOTE: (Never EVER use H1 in the body. It's here for completeness)*** + +`## H2 is this` produces: +## H2 is this +`*this is italics*` and `**this is bold**` and `***this is both***` illustrated in regular paragraph text: + +Here is some paragraph text. Pariatur *this is italics* and **this is bold** and ***this is both*** commodo et nisi ea est nulla enim ad id consequat aliquip. Proident anim est ad officia nostrud excepteur anim reprehenderit elit anim est irure pariatur. Duis ipsum anim dolor veniam voluptate occaecat cupidatat incididunt aliquip adipisicing officia dolor. Irure proident esse ullamco qui consequat elit excepteur qui velit proident cupidatat commodo amet. Tempor duis et qui dolore ex tempor esse dolore laboris ullamco deserunt. Nisi Lorem cupidatat aliqua elit commodo occaecat incididunt. In id sit et in consectetur eu incididunt aliquip Lorem deserunt et id non aliquip. + +`### H3 is this` produces: +### H3 is this + +`#### H4 is this` produces: +#### H4 is this + +`##### H5 is this` produces: +##### H5 is this + +`###### H62 is this` produces: +###### H6 is this + +------------------------------------------ + +## Images + +`` + +Sometimes you want an image to live on the left. Veniam deserunt do magna nisi sunt ea quis aliqua aute cupidatat elit Lorem non. Dolore veniam deserunt nisi aute magna. Officia id dolor aliqua sunt dolor id cupidatat quis ea elit excepteur ea non. Aute sint aute in enim pariatur veniam ut. Ut Lorem anim occaecat aliquip quis irure ipsum elit do deserunt consequat aute cillum. Magna dolore sint adipisicing labore deserunt. Incididunt culpa laboris nisi Lorem excepteur. + +`` + +Other times it belongs on the right. Veniam deserunt do magna nisi sunt ea quis aliqua aute cupidatat elit Lorem non. Dolore veniam deserunt nisi aute magna. Officia id dolor aliqua sunt dolor id cupidatat quis ea elit excepteur ea non. Aute sint aute in enim pariatur veniam ut. Ut Lorem anim occaecat aliquip quis irure ipsum elit do deserunt consequat aute cillum. Magna dolore sint adipisicing labore deserunt. Incididunt culpa laboris nisi Lorem excepteur. + +------------------------------------------ + +## Embeds + +This is mainly for youtube videos. Just use the regular youtube embed code wrapped in a `responsive-embed` `div` + +``` +
+ +
+``` + +
+ +
+ +------------------------------------------ + +## Tables + +Sometimes you need tabular data: + +| Header1 | Col A | Col B | Col C | +| --------- | ------- | ------- | ------- | +| **Row 1** | 0.23423 | 0.23423 | 0.23423 | +| **Row 2** | 0.23423 | 0.23423 | 0.23423 | +| **Row 3** | 0.23423 | 0.23423 | 0.23423 | + +Produced with: +``` +| Header1 | Col A | Col B | Col C | +| --------- | ------- | ------- | ------- | +| **Row 1** | 0.23423 | 0.23423 | 0.23423 | +| **Row 2** | 0.23423 | 0.23423 | 0.23423 | +| **Row 3** | 0.23423 | 0.23423 | 0.23423 | +``` + +------------------------------------------ + + +## Buttons + +### Basic Buttons + +Basic buttons can be produced as follows: + + +`Learn More`: +Learn More + +`View All Features`: +View All Features + +### Button Sizes + +Sometimes you want buttons of different sizes: +``` +So Tiny +So Small +So Basic +So Large +``` +So Tiny +So Small +So Basic +So Large + +Sometimes you want your buttons to expand the width of the page. +``` +Such Expand +Wow, Small Expand +``` +Such Expand +Wow, Small Expand + +### Button Coloring + +Coloring buttons can be done as follows: +``` +Primary +Secondary +Success +Alert +Warning +``` +Primary +Secondary +Success +Alert +Warning + +### Hollow Buttons +The same colors can be used on hollow buttons: +``` +Primary +Secondary +Success +Alert +Warning +Disabled +``` +Primary +Secondary +Success +Alert +Warning +Disabled + +### Buttons with Icons + +We use [font-awesome](https://fontawesome.com/v4.7.0/) icon set for icons + +` 'home' icon ` + 'home' icon + +Maybe you want a custom icon: + +` 'home' icon ` + 'home' icon + +----------------------------------------- + +## Block-grids + +Block grids are a shorthand way to create equally-sized columns. + +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +``` +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+``` + +------------------------------------------ + +## Cards + +Cards can be used to display items of a similar class + +
+
+
+ +
+

This is a row of cards.

+

This row of cards is embedded in an Flex Block Grid.

+
+
+
+
+
+ +
+

This is a card.

+

It has an easy to override visual style, and is appropriately subdued.

+
+
+
+
+
+ +
+

This is a card.

+

It has an easy to override visual style, and is appropriately subdued.

+
+
+
+
+``` +
+
+
+ +
+

This is a row of cards.

+

This row of cards is embedded in an Flex Block Grid.

+
+
+
+
+
+ +
+

This is a card.

+

It has an easy to override visual style, and is appropriately subdued.

+
+
+
+
+
+ +
+

This is a card.

+

It has an easy to override visual style, and is appropriately subdued.

+
+
+
+
+``` + + +-------------------------------------------- + +## Advanced grid work + +Everything in foundaiton is rows and columns. There are always 12 columns in a row: + +Grids can also behave differently at different sizes (think phone vs. desktop) + + +
+
+
small-2 large-4
+
small-4 large-4
+
small-6 large-4
+
+
+
large-3
+
large-6
+
large-3
+
+
+
+
+
+
+
+ +``` +
+
+
small-2 large-4
+
small-4 large-4
+
small-6 large-4
+
+
+
large-3
+
large-6
+
large-3
+
+
+
+
+
+
+
+``` \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/subdomain.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/subdomain.md new file mode 100644 index 0000000..8303e21 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/subdomain.md @@ -0,0 +1,35 @@ +--- +title: Get a Custom Subdomain +weight: 10 +--- + +By default, your GitHub site has a URL that is inherited from the Organization yoru repository is hosted in (or your user profile). For example, for the [Rivercapes](https://github.com/Riverscapes) organization, the default address will be `https://riverscapes.github.io/reponame/` where `reponame` is the name of your repository. + +This is controlled in your repository → *Settings*: + +![repname](\assets\images\tools\repname.png) + + + +You will notice that many of the higher-grade Riverscapes Tools have subdomains to `riverscapes.net`, instead of the above default. For example the [BRAT tool](https://brat.riverscapes.net) is `https://brat.riverscapes.net` where **brat**` is the custom subdomain. The RC will consider requests for any tools pending Riverscapes Compliance or fully [Riverscapes Compliant](https://riverscapes.net/Tools/#riverscapes-compliant-tools). + +## Step 1 - Request the subdomain you want +To request a subdomain for your tool, fill out the [form](https://forms.gle/H7jRGuf2QmypXkxN9) below. + +
+ +
+ +## Step 2 - Update URL Settings + +Once you have your subdomain set up (we'll notify you), you need to update yoru URL settings in both your repository and your website `_config.yml` file. + + + +### Update the URL in `_config.yml` + +![repname](\assets\images\tools\YML.png) +### Update the URL in GitHub Page Settings +Go to your repository settings, scroll down to GitHub pages and update the custom domain: + +![repname](\assets\images\tools\URLName.png) diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/testing_locally.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/testing_locally.md new file mode 100644 index 0000000..4025920 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/testing_locally.md @@ -0,0 +1,93 @@ +--- +title: Testing Sites Locally +--- + +It's always a good idea to verify changes locally before pushing them to GitHub. This avoids potentially breaking a site, or having to a push simply to visualize your work (only to realize a minor typo and then stage-commit-push a second time). To do this you need to run Jekyll locally on your computer and then point your browser at your localhost. Unfortunately Jekyll is coded in Ruby which can be tricky to install on Windows. Follow these one-time set-up instructions then at the bottom, the new command for running a Jekyll site from your computer: + +* [Windows](#windows) +* [Mac OSX](#osx) + +## Windows + +### 1. Check if Ruby is installed + +1. [Open a DOS command Window](https://www.isunshare.com/windows-10/4-ways-to-open-command-prompt-in-windows-10.html) (press the Windows key and then type `cmd` and hit enter) +1. Type the command `ruby --version` to check if you have Ruby installed and which version you might be running. +1. If you get "command not found" because Ruby is not installed then proceed to the next section. +1. We need a Ruby version that's equal to or newer than 2.1.0 so reinstall Ruby if you have an older version. + +### 2. Install Ruby (if necessary) + +1. Download the [Ruby installer](https://rubyinstaller.org/downloads). You want: Ruby+devkit 2.6.4 (exact number doesn't matter. Just choose the greatest Ruby+Devkit version) +1. Run the installer and choose all the default choices. +1. When the command line choice comes up choose **Base installation** + +``` + 1 - MSYS2 base installation <------ choose this one: (1) + 2 - MSYS2 system update (optional) + 3 - MSYS2 and MINGW development toolchain +``` +At the second prompt just hit ENTER to get out. + +Now go back to **Step 1: Check Version of Ruby**. There's no point in proceeding if you're running an old version or the installation failed. + +### 3. Install Bundler + +Back at the DOS command window, type the following command: + +``` +gem install bundler +``` + +### 4. Site-level (Do this for every site you want to serve locally) + +1. Open a DOS command window in the `/docs` folder of the site you want to serve. +1. Run the following command to install all the necessary components needed for the current site: + +``` +bundle install +``` + +### 5. Serving a site locally + +With the one-time steps above complete, you're good to go. You shouldn't have to run bundler install again and can just run the following command every time you want to serve a site: + +``` +bundle exec jekyll serve +``` + + +You should see something like this: + +``` +Configuration file: /Path/To/my-website/_config.yml + Source: /Path/To/my-website + Destination: /Path/To/my-website/_site + Incremental build: disabled. Enable with --incremental + Generating... + Remote Theme: Using theme riverscapes/riverscapes-jekyll-theme + done in 13.892 seconds. + Auto-regeneration: enabled for '/Path/To/my-website' + Server address: http://127.0.0.1:4001 + Server running... press ctrl-c to stop. +``` + +Note that this is telling you to navigate to `http://127.0.0.1:4001` in your browser in order to see the site. + +#### Some finer points + +* This service will rebuild the site every time you save a markdown `.md` file. You must **refresh your browser** to see the changes. +* `Ctrl-c` to exit the process. +* If you change the `_config.yml` file you will need to exit the process and restart. + +--------------------------- + +## OSX + +Mac OS comes with ruby pre-install so you should be able to jump ahead and install `bundler` directly. + +Start at step #3 in the Windows installation instructions above. All the steps are the same from there. + +### Advanced + +If you've somehow changed your OSX ruby installation or you wish to use your own version you can [install Homebrew](https://brew.sh/) to get things working. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/theming.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/theming.md new file mode 100644 index 0000000..a92d160 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/theming.md @@ -0,0 +1,59 @@ +--- +title: Theming a Tool Web Site +weight: 6 +--- + +We have developed a single theme that controls the look and feel of sites related to riverscapes. It's the theme that's applied to this site. If you have a Riverscapes site that doesn't look like this page or is missing page elements used on this site, then you need to follow the instructions below. + +These instructions describe how to apply this theme to both a new site, or update the theme for an existing site. The steps are manual and somewhat fiddly. Remember to review your changes in git before commiting them. You can always [run Jekyll locally](jekyll_toolbox.html#running-jekyll-locally) to ensure that your changes have not broken the site. + +## Before You Start + +You are going to need a copy of the Riverscapes **[riverscapes-jekyll-theme](https://github.com/Riverscapes/riverscapes-jekyll-theme)** repo. You can either use the green `Clone or Download` button on the [repo's GitHub web page](https://github.com/Riverscapes/riverscapes-jekyll-theme), or you can use git to clone down the repo. Regardless, make sure that you have the **latest version**. This theme will change from time to time. + +Now you are ready to apply the theme to your site. + + +# Theming a New Web Site + +These instructions assume that you have already [created your GitHub web site](/Technical_Reference/Documentation_Standards/WebSites/#creating-a-web-site). + +If you are unsure about any of these instructions then you can there is a [sample site available that can be used as a template](https://github.com/Riverscapes/riverscapes-jekyll-theme/tree/master/docs). Simply copy the contents of this docs folder into your repo and start from there. + +1. Create a file in your docs folder called `_config.yml` and cut and paste the [site configuration](https://raw.githubusercontent.com/Riverscapes/riverscapes-jekyll-theme/master/docs/_config.yml) into it. +1. Edit the `_config.yml` file and change the following: + 1. Change the title to the name of your tool + 1. Change the description. + 1. *Optionally* - Change the URL to where your site is served. +1. Commit the changes to your repo on the master branch and then push. + +## References +1. The `Gemfile` uses the [ruby gem configuration](https://raw.githubusercontent.com/Riverscapes/riverscapes-jekyll-theme/master/docs/_config.yml). +1. The `.gitignore` should follow [git ignore contents](https://raw.githubusercontent.com/Riverscapes/riverscapes-jekyll-theme/master/docs/.gitignore). +1. The folder called `assets` is where a folder called `images`exists. Put all the images for your site in here. + + +# Advanced Theming Topics + +## Sidebar + +You can add content to the left side of every page in a site by creating a file called `sidebar.html` inside a folder called `_includes` inside your docs folder. i.e. at the path (`/docs/_includes/sidebar.html`). Inside this file you can write any HTML you want and it will get injected into every page of the site underneath the site navigation panel. + +## Custom CSS + +You can extend the styling of a site by creating a file called `custom.css` at the location `/docs/assets/css`. The riverscapes theme already includes the following web libraries that you can use in your customizations: + +* [Foundation](https://foundation.zurb.com/) +* [Font Awesome 4.7](https://fontawesome.com/v4.7.0/) (note the version number) + + +## Updating your favicon + +Favicons are little graphics that web browsers display on the browser tab beside the site title: + +![favicon](/assets/images/favicon_demo.png) + +Favicons used to be simple. Things have gotten more complicated, what with all the various devices and resolutions on which people could be viewing your site. Here's how you generate your own: + +1. Find a nice sized copy of your logo that is square. A high quality image is most important, but also try to avoid images greater than 500 pixels across to avoid image distortion. +1. Go to a service like and upload your icon. It will generate lots images in various sizes. Use all 27 of these files in the folder to overwrite the files in `assets/images/favicons`. Make a comit and push to master. diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/writing_content.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/writing_content.md new file mode 100644 index 0000000..0d0c45b --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/WebSites/writing_content.md @@ -0,0 +1,129 @@ +--- +title: Writing Content +weight: 3 +--- + +This page contains techniques for enhancing web sites stored on GitHub. GitHub uses [Jekyll](https://jekyllrb.com) to take a set of documents written in [markdown](https://en.wikipedia.org/wiki/Markdown) and publish them as a full blown web site. What follows are several tricks, techniques and patterns for enhancing these Jekyll web sites with features that make the web sites more useful. For example, adding a table of contents or injecting a page header. + +## Front Matter + +Every markdown document in your site should contain a small section at the top that is referred to as *front matter*. This section contains a series of tags and keywords that Jekyll injects into the final web page. The most common and important tag is the `title` tag. Jekyll uses this to set the HTML page title for each document. + +Front matter must occur at the very top of every markdown document. It begins and ends with three hyphens, on their own lines in the file. Inside the front matter is a series of keywords, followed by a colon, a space and then the value for the item. Note that the keyword, in this case `title`, **is case sensitive**! So setting the page title would look like: + +``` +--- +title: This Is My Page Title +--- + +Page content goes below the front matter.... +``` + +The front matter title (i.e. *This is My Page Title* in the example above) is used in two ways: + +1. It is inserted at the top of every page, right under the header banner. i.e. You don't need to start every page with a title because it is done for you. +2. It is used as the link text in the site table of contents (see next section). + +## Site Table of Contents + +We have written JavaScript that automatically builds and displays a site table of contents (ToC) that is displayed on the left of each page. This ToC is generated by scraping the front matter (see previous section) `title` from each web page in a site. These titles are organized by the names of folders in which the pages are stored and displayed as a hierarchical set of collapsible links. Note that underscores in folder names are replaced with spaces. Also folder names are case sensitive. + +You can turn on/off whether a link to the site home page is shown at the top of the ToC. You can also control whether the ToC is first displayed as expanded. The default is for the ToC to initialize collapsed. These two settings are controlled from the `_config.yml` file in the root of the web site: + +``` +sideMenu: + homeItem: true + startExpanded: false +``` + +## Page Sorting + +By default, pages at each level of the table of contents are sorted alphabetically. However, you can sort pages by adding a `weight` front matter tag that specifies the order in which pages are added to the table of contents. It looks like this: + +``` +--- +title: My Page Title +weight: 1 +--- +``` + +The weight tag is **case sensitive** and the value should be a positive integer. The code that creates the table of contents attempts a simple sort on all pages at a specific level using this integer. The result is that pages possessing a valid sort weight are presented first, followed by other pages that do not possess a weight. These unweighted pages are sorted alphabetically. + +Technically, it doesn't matter what the weight values represent or where they start at; they can start at zero or one or any other positive integer. Best practice is to start the weights at 1. another trick is to weight pages that you want to *sink* to the bottom with a value of 99. This gives you lots of space to grow a directory with new pages without having to change existing weights. + +See the next section on how to sort directories. + +## Parent/Child Page Relationships + +The site ToC nests pages according to the directory structure of the markdown pages that make up the site. Therefore, to group a series of pages together and indent them in the ToC, create a subdirectory and place all the pages in there. By default, the directory name is used as the text of the parent label in the ToC. The directory name is case sensitive and underscorese are replaced with spaces. + +If you want the directory to be represented as a link to some page contents then create an `index.md` file in the directory. Remember to include a front matter `title` and this will be used as the link text in the site ToC. Adding a weight to the `index.md` controls the sorting of subdirectories. Similar to pages, all subdirectories that possess an index.md with a weight are sorted first, then unsorted directories are listed alphabetically below. + +## Page Contents + +A Hierarchical list of headers (H1, H2, H3) is displayed at the top left of each page. Remember that in markdown these are represented using asterix: + +``` +* My header 1 + +** My Header 2 + +*** My Header 3 +``` + +**Useful Trick**: If you want to share a link to a section within a page, then click on the link in the Page Contents and it will set the page to the URL to the corresponding section. + +You can turn off this page contents box for all pages or just the home page using settings in the `_config.yml` file in the root of the web site: + +``` +autoPageContents: + active: true + onHome: true +``` + + + +## Useful Links + +The useful links section comprises an unordered list of bullets with hyperlinks to helpful external web sites. This list is hard coded into the file `src\_includes\sidenav.html`. + +## Footer + +The footer displayed on every page is stored in the file `src\_includes\footer.html`. + +## Framework + +We have implemented a *framework* called [Foundation](http://foundation.zurb.com/) on our GitHub Pages web sites that handles making the site *responsive*. This is the technical term for making the site look good on any device. Here's a [cheat sheet](https://sudheerdev.github.io/Foundation5CheatSheet/) of Foundation CSS classes that you use when styling your site. (FYI Foundation is an alternative to the popular [BootStrap](http://getbootstrap.com/)) + +## CSS + +Short answer first... If you want to override the style of elements you can add custom CSS to the file at `assets\css\custom.css`. A typical way to do this is to first display the page in question. Then in Google Chrome, right click on an element and choose `Inspect`. Click on the piece of content that you want to style and Chrome will show the corresponding HTML in the bottom half of the screen. You should be able to gleam the class or ID of the element in question and style it accordingly in the custom.css file. + +OK... don't do any of that! Styling individual elements is tedious and error prone. For example, if you want to change the color of links throughout a site you might have to create a dozen custom CSS items. You'll quickly create a rats nest of custom CSS that is hard to maintain. + +These sites actually build CSS using a completely separate scripting language called [SASS](http://sass-lang.com/). SASS allows you to write more advanced CSS rules and then, from this code, generate the traditional CSS file. Essentially you write a powerful styling script then a SASS software engine downgrades it to dumb, traditional CSS that web sites use. It does some other tricks too, such as minify the CSS by removing unnecessary whitespace to make it faster on client browser. + +In summary, if you want to overhaul the style of one of these web sites, you need to know SASS... + +## Banner Image + +Store a banner image for your site in the `assets\images` folder of your site. Then refer to it in the `src\_layouts\default.html` file (around line 42). Here's the BRAT example that allows the banner image to link back to the home page for the site: + +``` +
+ +
+ BRAT +
+
+``` + +## YouTube Videos + +The easiest way to embed YouTube videos in Jekyll markdown web sites is to use the `IFRAME` tag: + +1. Navigate to the YouTube video in question +2. Click on the `Share` button underneath the video. +3. Click on the `Embed Button`. +4. Copy the text provide and paste it into your markdown page. Typically you can delete the wrapping `div` tag and just keep the `iframe` tag. + diff --git a/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/index.md b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/index.md new file mode 100644 index 0000000..85ba68d --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/Documentation_Standards/index.md @@ -0,0 +1,54 @@ +--- +title: Documentation Standards +weight: 1 +--- + + +
+
+
+ +
+

Intended Audience

+
    +
  • RC - Tool Developers
    • +
  • RC - Website/Documentation Contributors
    • +
+
+
+
+ +
+ + + + +Consistent documentation is fundamental to the riverscapes consortium philosophy. In practical terms this minimally involves the following types of documentation: + +* [Source code documentation](Source_Code) explaining the various components of a tool and how they work +* [Tool web sites](WebSites) for end users to discover, download and run the tools +* [Riverscapes Projects](Riverscapes_Projects) metadata to accompany the outputs of each tool + +The above resources are intended as a reference and guide for RC developers and website contributors. + +### Best Practice Examples + +#### BRAT - A New Research-Grade Script +In the case of tools or models that represent novel, new and/or significant methodological advances or scientific contributions, the model should also be vetted in the peer-reviewed scholarly literature. For example, the RC [BRAT](http://brat.riverscapes.net) (Beaver Restoration Assessment Tool) beaver dam capacity model (BRAT) was originally vetted in: +- Macfarlane W.W. , Wheaton J.M., Bouwes N., Jensen M., Gilbert J.T., Hough-Snee N., and Shivick J. 2015. [Modeling the capacity of riverscapes to support beaver dams](https://www.researchgate.net/publication/285590037_Modeling_the_capacity_of_riverscapes_to_support_beaver_dams). Geomorphology. DOI: [10.1016/j.geomorph.2015.11.019](http://dx.doi.org/10.1016/j.geomorph.2015.11.019). + +However, BRAT's +- Source code documentation is in its open-source [Riverscapes](https://github.com/Riverscapes) GitHub repo in the Riverscapes: +[https://github.com/Riverscapes/pyBRAT/](https://github.com/Riverscapes/pyBRAT/) +- The tool website at [https://brat.riverscapes.net]( https://brat.riverscapes.net) has all the end-user tool documentaoin +- Examples of BRAT data are available in Riverscapes Warehouses from [https://brat.riverscapes.net/BRATData]( https://brat.riverscapes.net/BRATData) + +### Tributary Impact - Implementing a Research Grade Script +By contrast, agorithms and methods that have already been published and vetted, but are simply packaged into an opensource tool for others to use should cite the original author + For example, the [Tributary Impact](http://tributaryimpact.riverscapes.net/) was originally vetted and presented in: +- Rice SP. 2017. Tributary connectivity, confluence aggradation and network biodiversity. Geomorphology 277 : 6–16. DOI: [10.1016/j.geomorph.2016.03.027](http://dx.doi.org/10.1016/j.geomorph.2016.03.027) + +However, the algorithm was coded up to implement and shared as +- Source code documentation is in its open-source [Riverscapes](https://github.com/Riverscapes) GitHub repo in the Riverscapes: +[https://github.com/Riverscapes/TributaryImpact](https://github.com/Riverscapes/TributaryImpact) +- The tool website at [http://tributaryimpact.riverscapes.net/](http://tributaryimpact.riverscapes.net/) and is minimally documented for transparency diff --git a/content/page/MIGRATED/Tools/Technical_Reference/database.md b/content/page/MIGRATED/Tools/Technical_Reference/database.md new file mode 100644 index 0000000..54ea92e --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/database.md @@ -0,0 +1,66 @@ +--- +title: Database Driven Tools +weight: 2 +--- + +Post from [@philpbaileynar](https://github.com/orgs/Riverscapes/people/philipbaileynar) + + +----- +# Background + + +We are increasingly relying on databases in our [riverscapes tools](/tools). Remember that the "I" in GIS stands for information. So if you don't know how to use a database you can't really call yourself a GIS expert! Still not convinced? [ESRI's](http://esri.com) first product back in the 1970s was called [ArcInfo](https://en.wikipedia.org/wiki/ArcInfo). The "Arc" referred to geometry while the "Info" literally referred to a tabular database. Yet, most GIS users (including most Riverscape Scientists) don't regularlly use databases directly. So not knowing databases means your skills are 40 years out of date! Here's how you can turn it all around... + +There are several popular brands of databases, some of which you might have heard of - [MySQL](https://www.mysql.com/), [Oracle](https://www.oracle.com/database/), [SQLite](https://www.sqlite.org/index.html), [Postgres](https://www.postgresql.org/), [SQLServer](https://www.microsoft.com/en-us/sql-server), [Access](https://www.microsoft.com/en-us/microsoft-365/access). They differ in lots of ways, but what they all share in common is that you interact with data using something called the [Structured Query Language](https://en.wikipedia.org/wiki/SQL) (SQL). Despite a few SQL nuances all the aforementioned database brands implement the same SQL standard for retrieving and managing data. The bottom line... **You need to learn the SQL language**. Here are some resources... + +# Resources +## For Book Lovers + +- [Getting Started With SQL](https://www.oreilly.com/library/view/getting-started-with/9781491938607/) (I really like O'Reilly books) + +## For Movie Lovers + +### PostGIS +[Introduction to PostGIS](https://youtu.be/g4DgAVCmiDE) (a geospatial extension to postgres) +
+ +
+ +### SQL +[Introduction to SQL](https://youtu.be/7S_tz1z_5bA) (this 3hr video course uses MySQL but I like Mosh, the presenter) +
+ + +
+ +## For Practical Types + +- [Code Academy SQL Course](https://www.codecademy.com/catalog/language/sql) +- [Software Carpentry](https://swcarpentry.github.io/sql-novice-survey/) + +## Software + + +The two types of open source database that we use are: + +- [SQLite](https://sqlite.org/about.html) - useful when you just want to store data on your computer and use it yourself. +- [Postgres](https://www.postgresql.org/) - hosted on a server and accessible by multiple people. + +If you're just starting out then I recommend SQLite and the O'Reilly book above. Note that SQLite itself does not have a user interface. It's literally just a file format for storing data. You will need a piece of software to open and work with SQLite files. For this I recommend [DataGrip](https://www.jetbrains.com/datagrip/). It's free with a university email address. + +## What about GIS? + +Basic SQL is not geospatial. I recommend learning the SQL language before delving further into geospatial databases. But if you're keen then you should know that we are using the open source [geopackage](https://www.geopackage.org/) to store GIS data on desktop computers (no more ShapeFiles!) and the [PostGIS](https://postgis.net/) extension to serve GIS data from online servers. + +Not convinced? As of November 2020 the outputs of the following tools are already geopackage SQLite databases: + +- [VBET](http://vbet.riverscapes.net) +- [Confinement](http://confinement.riverscapes.net) +- [RVD](http://rcat.riverscapes.net) + +We will soon migrate [BRAT](http://brat.riverscapes.net) to output a SQLite geopackage and stop using ShapeFiles. The new reach typing tool for the Mississippi, as well as [GNAT](http://gnat.riverscapes.net/) will also use databases. Our reporting technology also relies on SQLite. + +----------- +# Summary +In summary... If you plan on working with riverscapes tools and data, it would be in your best interest to learn SQL. \ No newline at end of file diff --git a/content/page/MIGRATED/Tools/Technical_Reference/videos.md b/content/page/MIGRATED/Tools/Technical_Reference/videos.md new file mode 100644 index 0000000..7756a43 --- /dev/null +++ b/content/page/MIGRATED/Tools/Technical_Reference/videos.md @@ -0,0 +1,44 @@ +--- +title: Visual Studio Code Demos +weight: 3 +--- + +Posts and videos from [@philpbaileynar](https://github.com/orgs/Riverscapes/people/philipbaileynar) to help you getting started with [Visual Studio Code](https://code.visualstudio.com/). +# Introduction to Visual Studio Code + +
+ +
+ +# XML Validation in Visual Studio Code + +
+ +
+ +Note, from time to time old versions of the XSD validation can get cached locally and may not be updating. If this happens, try: +1. shut down VSCode completely +2. Go to your used folder (usually somethin like `c:\Users\MYNAME\`) +3. Look for a `.lemminx` folder. Inside that you should find a `cache` folder +4. Delete the `cache` folder completely. +5. Open up VSCode + +# Logging In Python + +The logging class used is the demo is available [here](https://github.com/Riverscapes/sqlBRAT/blob/master/lib/loghelper.py). + +
+ +
+ +# Opening Feature Classes and Looping Over Features + +
+ +
+ +# Removing Hard Coded Paths By Passing Arguments + +
+ +
diff --git a/content/page/MIGRATED/Tools/discrimination.md b/content/page/MIGRATED/Tools/discrimination.md new file mode 100644 index 0000000..1222746 --- /dev/null +++ b/content/page/MIGRATED/Tools/discrimination.md @@ -0,0 +1,140 @@ +--- +title: Tool Discrimination +weight: 4 +--- + +# Tool Discrimination + Discriminating tools helps potential users of the tool or users of its outputs make informed decision about whether the tool and/or its outputs are fit for _their_ purposes. The following are helpful concepts the RC uses for discriminating model types: + +- [Interface](#interface) +- [Tool-Grade](#tool-grade) (using adaptation of NASA's [Technological Readiness Levels](#technological-readiness-levels)) +- [Report Cards]({{ site.baseurlf }}/Tools/reportcards.html) + +What exactly is the tool itself? Tools can be defined as1: +> a: something (such as an instrument or apparatus) used in performing an operation or necessary in the practice of a vocation or profession. *a scholar's books are his tools* +> +> b: an element of a computer program (such as a graphics application) that activates and controls a particular function. *a drawing tool* + +Here, we are referring to **tools** as a computer program (similar to b), that takes input data, operates on it and produces output(s). We do not consider **tools** to be the many individual commands or functions within a specific tool (some might call such tools a toolset, or toolbox). However, we recognize that for many audiences and end-users, the output data alone is itself a "tool" to inform practice or decision making (e.g. [BRAT](http://brat.riverscapes.net)). However, in those instances the user might be more effectively consuming the outputs of a **tool** (or model, similar to definition a above) via something like the [Riverscapes Viewer](https://rave.riverscapes.net) or our [Riverscapes Warehouse](/Data_Warehouses/) . + + +## Interface + +RC**tools** are deployed to users thorugh a variety of interfaces: +* : [ArcGIS AddIn](https://desktop.arcgis.com/en/arcmap/10.7/guide-books/python-addins/sharing-and-installing-add-ins.htm) ArcGIS [AddIn Toolbar](https://desktop.arcgis.com/en/arcmap/10.7/analyze/python-addins/sharing-and-installing-add-ins.htm) in ArcGIS +* : [ArcPy Toolbox in ArcGIS](https://desktop.arcgis.com/en/arcmap/10.7/analyze/creating-tools/a-quick-tour-of-python-toolboxes.htm) +* [QGIS Plugin](https://plugins.qgis.org/) = Toolbar in [QGIS](https://qgis.org) +* : CLI = [Command Line Interface](https://en.wikipedia.org/wiki/Command-line_interface) +* : GUI = [Graphical User Interface](https://en.wikipedia.org/wiki/Graphical_user_interface) +* : Web = interactive web site +* : API = [Application Programming Interface](https://en.wikipedia.org/wiki/Application_programming_interface) +* : App = [Mobile App](https://en.wikipedia.org/wiki/Mobile_app) + +Most tools have just one deployment interface, some have multiple. + +## Tool Grade +We classify the grade of our tools along a continuum of growth from innovative research [ideas](#concept), through to [operational](#operational-grade) tools in development that (with a little love and patience) can be run by someone other than the developer, on through to more broadly deployable [professional](#professional-grade) tools that are robust and usable by any user in very different settings. Tools that have the potential to be efficiently run with greater repetition and/or across greater spatial extents or at greater resolution may be upgraded to [production-grade](#production-grade) tools whereas those that can then be deployed to much broader audiences in the most accessible platforms (e.g. Mobile Aps, Web Aps) and with ease of sharing maybe ultimately be launched as [commercial-grade](#commercial-grade) tools. + +
+ +
+ + +Our [RC Technical Committee](\About\) ranks a **tool's grade** status using the following criteria: + +| [Technology
Readiness Level](#technological-readiness-levels) | Tool Status |Badge | Vetted in
Peer-Reviewed
Literature | Source Code
Documentation | Open Source | User
Documentation | Easy User
Interface | Scalability | +|:-----------------------------:|------------------------|:------------------------------------------------------:|:--------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------:| +| TR1 -TR2 |[**Concept**](#concept)| | | | | | | | +| TR3 |[**Proof of Concept**](#proof-of-concept)| | | |
to
| | | | +| TR4 |[**Research Grade**](#research-grade)| | | | | |
to
|
to
| +| TR5-6 | [**Operational Grade**](#operational-grade)|| | | | | | | +| TR7-8 |[**Professional Grade**](#professional-grade)| | | | |