Merge pull request #40 from nsidc/readthedocs

Init readthedocs

.gitignore

@@ -142,4 +142,7 @@ cython_debug/
 *~
 
 # zipfiles
-*.zip
+*.zip
+
+# ctags
+/tags

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: help/source/conf.py
+  # There doesn't seem to be a way to turn on nitpicky mode.
+  # This is equivalent to `-W --keep-going`.
+  fail_on_warning: True
+
+formats:
+  - pdf
+
+python:
+  install:
+    - requirements: help/requirements.txt

README.md

@@ -1,4 +1,33 @@
-# QGreenland plugin
+[![NSF-1928393](https://img.shields.io/badge/NSF-1928393-red.svg)](https://nsf.gov/awardsearch/showAward?AWD_ID=1928393)
 
-The QGreenland plugin for QGIS allows to download dataset from the QGreenland
-project.
+# QGreenland Custom
+
+The QGreenland Plugin allows direct access to QGreenland layers without
+downloading the full QGreenland Package.
+
+[Our website](https://www.qgreenland.org) |
+[Documentation](https://qgreenland-plugin.readthedocs.io)
+
+
+## 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 'Towns and settlements' and 'Community map
+(crowdsourced)' 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.

help/requirements.txt

@@ -0,0 +1,3 @@
+sphinx ~=4.3.2
+sphinx-rtd-theme==1.0.0
+myst-parser==0.15.2

help/source/citing.md

@@ -0,0 +1,16 @@
+# Citing QGreenland
+
+We request that QGreenland be cited or acknowledged when publishing a
+QGreenland-made image or map.
+
+
+## Citation
+
+> Moon, T., M. Fisher, L. Harden, & T. Stafford (2021). QGreenland[software].
+> Available from https://qgreenland.org.
+> https://doi.org/10.5281/zenodo.4558266.
+
+
+## Acknowledgement
+
+> We acknowledge the National Snow and Ice Data Center QGreenland package.

help/source/conf.py

@@ -11,7 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import datetime
+import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -25,7 +27,12 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.imgmath', 'sphinx.ext.viewcode']
+extensions = [
+    'myst_parser',
+    'sphinx.ext.todo',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.viewcode',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -40,8 +47,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'QGreenland'
-copyright = u'2013, Matteo Ghetta (Faunalia)'
+project = u'QGreenland Custom'
+copyright = f'NSIDC {datetime.date.today().year}'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -91,7 +98,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,7 +127,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

help/source/contributor-how-to/develop.md

@@ -0,0 +1,29 @@
+# How to develop QGreenland Custom
+
+## Development QGIS plugin install
+
+Install the plugin by symlinking this repository to your plugins directory,
+e.g.:
+
+```
+ln -s $PWD ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/.
+```
+
+Then in the QGIS "Manage and Install Plugins..." dialog's "Installed" tab,
+ensure the "QGreenland" plugin is enabled (checked).
+
+Use Plugin Reloader to reload the plugin after each change.
+
+
+## Edit docs
+
+To preview docs locally, create a local environment and install dependencies,
+then make the docs.
+
+```
+cd help
+virtualenv env
+. env/bin/activate
+pip install -r requirements.txt
+make html
+```

help/source/contributor-how-to/index.rst

@@ -0,0 +1,11 @@
+.. _contributor-how-to:
+
+=========================
+Contributor how-to guides
+=========================
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*

help/source/index.rst

@@ -1,20 +1,33 @@
-.. QGreenland documentation master file, created by
-   sphinx-quickstart on Sun Feb 12 17:11:03 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. QGreenland Custom documentation master file, created by sphinx-quickstart on
+   Sun Feb 12 17:11:03 2012.  You can adapt this file completely to your
+   liking, but it should at least contain the root `toctree` directive.
 
-Welcome to QGreenland's documentation!
-============================================
-
-Contents:
+=================
+QGreenland Custom
+=================
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
+
+   ./what_is_qgr_custom.md
+   ./citing.md
+
+
+.. toctree::
+    :name: How-to
+    :caption: How-to
+    :maxdepth: 1
+    :hidden:
+
+    ./contributor-how-to/index
+
+
 
-Indices and tables
-==================
+.. only:: builder_html
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    .. include:: what_is_qgr_custom.md
+        :parser: myst_parser.sphinx_
 
+    .. include:: citing.md
+        :parser: myst_parser.sphinx_

help/source/what_is_qgr_custom.md

@@ -0,0 +1,6 @@
+# What is QGreenland Custom?
+
+QGreenland Custom is a QGIS plugin that enables you to access only the
+QGreenland layers you are interested in. If you want the Core QGreenland
+package, check out [the docs for that
+project](https://qgreenland.readthedocs.io).

qgreenland.py

@@ -32,6 +32,8 @@
 from .qgreenland_server import QGreenlandServer
 import os.path
 
+import webbrowser
+
 
 class QGreenland:
     """QGIS Plugin Implementation."""
@@ -183,6 +185,14 @@ def initGui(self):
             parent=self.iface.mainWindow()
             )
 
+        self.add_action(
+            icon_path,
+            text=self.tr(u'Help'),
+            callback=self.run_help,
+            add_to_toolbar=False,
+            parent=self.iface.mainWindow()
+            )
+
 
         # will be set False in run()
         self.first_start = True
@@ -235,3 +245,9 @@ def run_manage_data(self):
 
         self.manage_dlg.exec()
 
+
+    def run_help(self):
+
+        help_url = 'https://qgreenland-plugin.readthedocs.io'
+        webbrowser.open(help_url)
+

scripts/build-docs.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -e
+
+THIS_DIR="$( cd "$(dirname "$0")"; pwd -P )"
+cd "$THIS_DIR"/../help
+
+make clean && make html