Merge pull request #711 from nsidc/update-readme-nsidc-template

Update README and other documentation

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at nsidc@nsidc.org. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

README.md

@@ -1,11 +1,19 @@
-[![NSF-1928393](https://img.shields.io/badge/NSF-1928393-red.svg)](https://nsf.gov/awardsearch/showAward?AWD_ID=1928393)
-[![DOI](https://zenodo.org/badge/241453043.svg)](https://zenodo.org/badge/latestdoi/241453043)
+<p align="center">
+  <img alt="NSIDC logo" src="https://nsidc.org/themes/custom/nsidc/logo.svg" width="150" height="150" />
+  <img alt="NSF logo" src="https://nsidc.org/sites/default/files/images/Logo/NSF.svg" width="150" height="150" />
+</p>
 
 # QGreenland
+[![NSF-1928393](https://img.shields.io/badge/NSF-1928393-red.svg)](https://nsf.gov/awardsearch/showAward?AWD_ID=1928393)
+[![DOI](https://zenodo.org/badge/241453043.svg)](https://zenodo.org/badge/latestdoi/241453043)
 
-![QGreenland example images](/doc/_images/qgreenland-examples.jpg)
+This repository is responsible for the code and configuration for creating the
+QGreenland Core zip package. To download the package and learn more about
+QGreenland, visit our [our website](https://www.qgreenland.org).
 
-[Our website](https://www.qgreenland.org) | [Documentation](https://qgreenland.readthedocs.io)
+For more detailed information about using the QGreenland Core zip package and on
+how to contribute to QGreenland, see our
+[Documentation](https://qgreenland.readthedocs.io)
 
 > :tada: QGreenland v3 development is well underway. We're looking for testers to
 > provide feedback by **August 6, 2023**. Please see our
@@ -15,78 +23,47 @@
 
 ## A Free GIS package for Greenland
 
-QGreenland is a free mapping tool to support interdisciplinary
-Greenland-focused research, teaching, decision making, and collaboration.
+![QGreenland example images](/doc/_images/qgreenland-examples.jpg)
 
-Combines key datasets into a unified, all-in-one GIS analysis and visualization
-environment for offline and online use.
+QGreenland is a free mapping tool to support interdisciplinary Greenland-focused
+research, teaching, decision making, and collaboration. It combines key datasets
+into a unified, all-in-one GIS analysis and visualization environment for
+offline and online use.
 
 An international Editorial Board and Project Collaborators connects the
 QGreenland Team to data and user communities.
 
+Learn more about [What is
+QGreenland?](https://qgreenland.readthedocs.io/en/latest/what_is_qgr.html)
 
-## Disclaimer
-
-QGreenland should not be used as a sole navigational aid while performing
-remote research activities in Greenland. Always bring appropriate safety and
-navigational aids (including hard-copies of topographic maps) when visiting the
-field.
-
-QGreenland is a data-viewing and analysis platform, and the QGreenland Team does
-not create new data. QGreenland's layers may contain errors from the original
-data providers. QGreenland makes no guarantees about the accuracy and validity
-of data contained in QGreenland. Limited notes on known data issues have been
-added to the 'Populated places' layer metadata. Also, some layers may not
-perfectly align with each other due to unidentified georeferencing issues with
-the original data. We recommend using the 'Greenland coastlines 2017' layer as
-the best approximation reference layer for geolocating Greenland's coastline.
-
-Note that some data were transformed from their native data formats,
-projections, and resolutions for inclusion within QGreenland. The included
-metadata (>Layer Properties >Metadata >History) contains provenance information
-on any transformations. All QGreenland GeoPackages and GeoTIFFs are projected
-in `EPSG:3413`.
 
+# Usage
 
-# Getting started
+## For contributors
 
-As of this writing, the oldest version of QGIS we support for the QGreenland release
-series are:
+Those wishing to utilize the `qgreenland` code to create their own QGreenland
+data package should see the contributor [How to build QGreenland
+Core](https://qgreenland.readthedocs.io/en/latest/contributor/how-to/run-qgreenland.html)
+guide.
 
-* QGreenland `1.x`: QGIS `3.16.x LTR`
-* QGreenland `2.x`: QGIS `3.16.x LTR`
-* QGreenland `3.x`: QGIS `3.28.x LTR`
+## For users of the QGreenland Core data package
 
-You can find downloads and instructions
-[here](https://qgis.org/en/site/forusers/download.html).
+See our [Get started with QGreenland
+Core](https://qgreenland.readthedocs.io/en/latest/user/tutorials/get-started.html)
+tutorial!
 
-After installing QGIS, [download QGreenland](https://qgreenland.org/download)
-and unzip it with your unzip tool of choice if you haven not already done so.
+### What is inside the QGreenland Core data package zip file?
 
-> :warning: Ensure QGreenland is _actually_ unzipped; some operating systems will only
-> "explore" a zip file when you double-click it without actually extracting it to disk.
-> In Windows, please right-click and select `Extract all...`.
+At the root of the zip file, you will find useful files such as a
+`UserGuide.pdf`, the `qgreenland.qgs` QGIS project file and scientific
+discipline-specific directories containing data (GeoTIFFs and GeoPackages). 
 
-Finally double-click on (or use QGIS open) the `qgreenland.qgs` file that was just
-extracted from the zip.
+For more detailed information, see our documentation on the [QGreenland Core
+Download
+Package](https://qgreenland.readthedocs.io/en/latest/what_is_qgr.html#qgreenland-core-download-package).
 
 
-## What's inside the QGreenland Core zip package?
-
-At the root of the zip file, you will find scientific discipline-specific directories
-containing data (GeoTIFFs and GeoPackages). Additionally, the following files are
-present at the package root:
-
-* `UserGuide.pdf`: Detailed user-guide.
-* `QuickStartGuide.pdf`: Guide for QGIS beginners.
-* `README.html`: The README file you are currently reading.
-* `CHANGELOG.html`: A summary of changes for each new QGreenland version.
-* `layer_list.csv`: Comma-separated values representing the configuration of
-  layers in QGreenland. This includes limited layer metadata, including, but not limited
-  to: title, description, abstract, and citation.
-
-
-# Educational resources
+### Educational resources
 
 We keep the QGreenland official website up-to-date with links to helpful
 educational resources, including our own QGreenland User Guide.
@@ -95,19 +72,26 @@ educational resources, including our own QGreenland User Guide.
 * [QGreenland YouTube channel](https://www.youtube.com/channel/UCjWae_Jrbognx2ju_SHBZ2A/videos)
 * [QGreenland official documentation](https://qgreenland.readthedocs.io)
 
+### Troubleshooting
+
+See our user troubleshooting guide
+[here](https://qgreenland.readthedocs.io/en/latest/user/how-to/troubleshooting.html).
 
 # Contributing
 
-Please see [contributing
-instructions](https://qgreenland.readthedocs.io/en/latest/contributor-how-to/contribute-layers.html)
-for more info. A good portion of this document contains technical instructions about
-running the QGreenland pipeline, but also includes less-technical instructions for
-contributing styles you have developed within QGIS. Our goal is to make it as easy as
-possible for any user of QGreenland to contribute to the project, so please do not be
-deterred from sharing your ideas.
+See our [discusson page on
+contributing](https://qgreenland.readthedocs.io/en/latest/contributor/discussion/contributing.html)
+to get started!
 
-**If all else fails, please [email us](mailto:qgreenland.info@gmail.com)!**
+Contributor documentation contains technical instructions about running the
+QGreenland pipeline code, but we also strive to describe everything clearly.
+Our goal is to make it as easy as possible for any user of QGreenland to
+contribute to the project, so please do not be deterred from sharing your ideas.
 
+If you have an idea for a new feature or have a bug to report, please submit an
+[Issue](https://github.com/nsidc/qgreenland/issues).
+
+**If all else fails, please [email us](mailto:qgreenland.info@gmail.com)!**
 
 # Acknowledgements
 

doc/contributor/discussion/contributing.md

@@ -32,7 +32,7 @@ Currently, layer styles can be contributed without any programming knowledge by
 designing the style in QGIS, saving it as a `.qml`, and committing it to the
 `qgreenland/ancillary/styles` directory.
 
-You can contribute to this project even if you don't have write access by
+You can contribute to this project even if you do not have write access by
 forking, making your change, making all CI checks pass, then opening a Pull
 Request. Learn more:
 
@@ -41,6 +41,10 @@ Request. Learn more:
 
 ### How-tos
 
-Visit [our
-documentation](https://qgreenland.readthedocs.io/en/latest/contributor-how-to/)
-for contributor-focused how-tos!
+See our [Contributor "How-to" guides
+](/contributor/how-to/index.rst) for
+how-tos on topics such as:
+
+* [How to build QGreenland Core](/contributor/how-to/run-qgreenland.md)
+* [How to contributing new layers](/contributor/how-to/contribute-layers.md)
+* [How to contribute styles](/contributor/how-to/contribute-styles.md)

doc/contributor/discussion/pydantic-and-mypy.md

@@ -6,10 +6,10 @@ While Pydantic uses type annotations to determine runtime validation behavior, i
 effectively overrides your annotation with `Any` (try `reveal_type(MyModel)`!). This is
 because Pydantic needs to be able to convert compatible values. [Pydantic's mypy
 plugin](https://docs.pydantic.dev/1.10/mypy_plugin/#plugin-settings), which we use,
-offers an `init_typed` setting, which we don't use, to "correctly" annotate the
+offers an `init_typed` setting, which we do not use, to "correctly" annotate the
 `__init__` method of models, with the downside that Mypy throws errors when you take
 advantage of Pydantic's type conversion behavior.
 
-For this reason, it's expected that QGreenland config files would **pass** type checking
-when instantiating Pydantic models with incorrect field types. These would instead
-**fail** runtime validation.
+For this reason, it is expected that QGreenland config files would **pass** type
+checking when instantiating Pydantic models with incorrect field types. These
+would instead **fail** runtime validation.

doc/contributor/how-to/contribute-layers.md

@@ -1,12 +1,12 @@
 # How to contribute new layers
 
 ```{note}
-We can't promise that your layer will be added, so please [open an
+We cannot promise that your layer will be added, so please [open an
 issue](https://github.com/nsidc/qgreenland/issues/new/choose) and start a
 discussion before developing a processing pipeline for a new layer. 
 ```
 
-It's recommended to use the CLI to create a dataset and/or layer template to
+It is recommended to use the CLI to create a dataset and/or layer template to
 help you along. In the below commands, replace filenames, paths, and ids with
 real ones. NOTE: When generating templates, but _not_ when fetching, you can
 use `./scripts/experimental/local_cli.sh config-template <dataset|layer>` in

doc/contributor/how-to/contribute-styles.md

@@ -12,7 +12,7 @@ following process:
 
 ![Save style](/_images/save_style.png)
 
-* At this point, if you're uncomfortable with Git and GitHub, you can email us
+* At this point, if you are uncomfortable with Git and GitHub, you can email us
   your style file at qgreenland.info@gmail.com. Otherwise, continue on...
 * Save the style to `qgreenland/assets/styles/<name>.qml` directory of this
   repository or your fork. Keep in mind that styles can be shared between
@@ -53,7 +53,7 @@ continuous legend. In the "Legend Settings" menu, ensure:
 e.g. `Font "Helvetica" font not available on system`.
 
 See [this GitHub issue](https://github.com/nsidc/qgreenland/issues/515) for more. For
-example it's possible your style `qml` file contains `fontFamily="Sans Serif"` and
-that's being automatically converted by PyQGIS to a value like `Helvetica` (a
+example it is possible your style `qml` file contains `fontFamily="Sans Serif"` and
+that is being automatically converted by PyQGIS to a value like `Helvetica` (a
 proprietary font) when writing the final project file. Try `fontFamily="Open Sans"`
 instead!

doc/contributor/how-to/release-new-version.md

@@ -14,7 +14,7 @@ Versions should be in one of the following forms:
 * `vX.Y.Z`: A final release, e.g. `v1.2.3`.
 
 ```{caution}
-When using `bumpversion build`, ensure you've already used `bumpversion
+When using `bumpversion build`, ensure you have already used `bumpversion
 prerelease`. Running `bumpversion build` from a final release version number
 can result in an incorrect patch number, e.g. `v1.2.304`.
 ```

doc/contributor/how-to/write-documentation.md

@@ -48,10 +48,11 @@ Our PDF doc is intended to be user-focused, but our HTML docs serve users and
 contributors (i.e. PDF docs are a subset of HTML docs). Most of the docs end up in both
 formats, so we want to use the same content to create both.
 
-Sphinx offers the `.. only::` directive for conditional content, but it does not work as
-one might intuitively expect. Specifically, it isn't capable of creating conditional or
-filtered `toctrees`. Because of this insufficiency, we're employing two nonstandard
-methods in `doc/index.rst` to deselect items from PDF docs:
+Sphinx offers the `.. only::` directive for conditional content, but it does not
+work as one might intuitively expect. Specifically, it isn't capable of creating
+conditional or filtered `toctrees`. Because of this insufficiency, we are
+employing two nonstandard methods in `doc/index.rst` to deselect items from PDF
+docs:
 
 * The package
   [sphinx-selective-exclude](https://pypi.org/project/sphinx-selective-exclude/)
@@ -99,7 +100,7 @@ the Docs.
 ## Contributing to documentation
 
 ```{attention}
-You'll need to have TeX Live installed if you want to render PDF documentation. On
+You will need to have TeX Live installed if you want to render PDF documentation. On
 Debian-based systems, you can install it with `sudo apt install texlive-latex-extra`.
 
 We attempted to include this dependency via the `conda` package `texlive-core`, but
@@ -114,7 +115,7 @@ it.
   material](https://diataxis.fr/reference/), or a [Discussion
   topic](https://diataxis.fr/explanation/)? Ensure your document is in the
   correct directory and written for the correct audience.
-* Write your documentation in Markdown, unless you're writing a page that must
+* Write your documentation in Markdown, unless you are writing a page that must
   be majority reStructuredText, such as an `index.rst` for a new group of pages.
 * Ensure your documentation page starts with a top-level header. This is the
   title of the page.

doc/contributor/reference/architecture/storage.md

@@ -55,13 +55,13 @@ data/private-archive
 ```
 
 While this project prefers to only include publicly-archived and
-machine-accessible data, we do have some privately-archived data that we've
+machine-accessible data, we do have some privately-archived data that we have
 sourced by e-mailing scientists or manually interacting with machine-unfriendly
-systems. These datasets have an `access_instructions` attribute in
-configuration that describes how the data was acquired.
+systems. These datasets have an `access_instructions` attribute in configuration
+that describes how the data was acquired.
 
 May be read-only.
 
 NOTE: The CLI's `run` command features an argument `--exclude-manual-assets`
-flag which will exclude any layers that depend on privately-archived data. It's
+flag which will exclude any layers that depend on privately-archived data. It is
 recommended to use this flag as a QGreenland contributor testing their changes.

doc/disclaimer.md

@@ -0,0 +1,21 @@
+# Disclaimer
+
+QGreenland should not be used as a sole navigational aid while performing remote
+research activities in Greenland or elsewhere. Always bring appropriate safety
+and navigational aids (including hard-copies of topographic maps) when visiting
+the field.
+
+QGreenland is a data-viewing and analysis platform, and the QGreenland Team does
+not create new data. QGreenland's layers may contain errors from the original
+data providers. QGreenland makes no guarantees about the accuracy and validity
+of data contained in QGreenland. Limited notes on known data issues have been
+added to the 'Populated places' layer metadata. Also, some layers may not
+perfectly align with each other due to unidentified georeferencing issues with
+the original data. We recommend using the 'Greenland coastlines 2017' layer as
+the best approximation reference layer for geolocating Greenland's coastline.
+
+Note that some data were transformed from their native data formats,
+projections, and resolutions for inclusion within QGreenland. The included
+metadata (>Layer Properties >Metadata >History) contains provenance information
+on any transformations. All QGreenland GeoPackages and GeoTIFFs are projected
+in `EPSG:3413`.