diff --git a/.readthedocs.yaml b/.readthedocs.yaml index ed79477d..ba77abce 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,19 +4,22 @@ version: 2 build: - os: ubuntu-20.04 + os: "ubuntu-20.04" tools: - python: "3.10" + # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python + python: "mambaforge-22.9" sphinx: - configuration: doc/conf.py + configuration: "doc/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 + - "pdf" -python: - install: - - requirements: doc/requirements.txt +# The build will run in an isolated `conda` environment; the version of Python +# is determined by the environment specification file. +# https://docs.readthedocs.io/en/stable/guides/conda.html +conda: + environment: "doc/environment.yml" diff --git a/doc/citing.md b/doc/citing.md index 6b49a001..07250fd3 100644 --- a/doc/citing.md +++ b/doc/citing.md @@ -18,12 +18,14 @@ is furnished to do so, subject to the following conditions: The above copyright permission notice shall be included in all copies or substantial portions of the Software. Users should note that published works produced using QGreenland are required to cite -each dataset used in the work. QGreenland provides all dataset citation information in each -layer’s metadata in QGIS (see the Layer Properties section in the Interacting with Geospatial -Data tutorial for instructions on how to access a layer’s metadata) and in the layer catalog -provided with the QGreenland download package, **layer_list.csv**. You are also required to +each dataset used in the work. QGreenland provides all dataset citation information in +each layer’s metadata in QGIS (see the [Layer Properties section in the Interacting with +Geospatial Data tutorial](#interacting-with-geospatial-data-layer-properties) for +instructions on how to access a layer’s metadata) and in the layer catalog provided with +the QGreenland download package, **layer_list.csv**. You are also required to acknowledge or cite QGreenland and the National Snow and Ice Data Center in your work. + ## Citation Please note that QGreenland currently has two citable components: diff --git a/doc/contributor/how-to/write-documentation.md b/doc/contributor/how-to/write-documentation.md index 6ea0bd6d..eec96b04 100644 --- a/doc/contributor/how-to/write-documentation.md +++ b/doc/contributor/how-to/write-documentation.md @@ -79,8 +79,8 @@ Sphinx or MkDocs under the hood, and we chose Sphinx. It runs automatically in response to changes in GitHub. It is configured by `.readthedocs.yml` at the root of this repository. -When Read the Docs builds our documentation, it uses the Python environment -defined by `doc/requirements.txt`. +When Read the Docs builds our documentation, it uses the environment defined by +`doc/environment.yml`. ### reStructuredText diff --git a/doc/environment.yml b/doc/environment.yml new file mode 100644 index 00000000..021fc8d2 --- /dev/null +++ b/doc/environment.yml @@ -0,0 +1,25 @@ +# For use by ReadTheDocs build system +name: qgreenland-docs +channels: + - conda-forge + - nodefaults +dependencies: + # TODO: Upgrade sphinx ones sphinx-rtd-theme supports 7 + # - sphinx ~=7.2.2 + - sphinx ~=6.2.1 + - latexmk ~=4.55 + - myst-parser ~=2.0.0 + - sphinx-click ~=3.0.1 + - sphinx-rtd-theme ~=1.2.2 + - autodoc-pydantic ~=1.9.0 + - pydantic <2.0.0a0 + + # What is this? Do we need it? + # sphinx-autodoc-typehints==1.12.0 + + # QGreenland's dependencies for autodoc. Should we mock these instead? + - anytree ~=2.8.0 + - funcy ~=1.16 + + - pip: + - sphinx-selective-exclude ~=1.0.3 diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 139c0237..00000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,13 +0,0 @@ -# Only for use by ReadTheDocs build system -myst-parser==0.15.2 -autodoc-pydantic ~=1.5.1 -pydantic <2.0.0a0 -sphinx-click==3.0.1 -sphinx-selective-exclude ~=1.0.3 - -# What is this? Do we need it? -# sphinx-autodoc-typehints==1.12.0 - -# QGreenland's dependencies for autodoc. Should we mock these instead? -anytree==2.8.0 -funcy==1.16 diff --git a/doc/user/tutorials/interacting-with-geospatial-data.md b/doc/user/tutorials/interacting-with-geospatial-data.md index adbd9d85..84ace766 100644 --- a/doc/user/tutorials/interacting-with-geospatial-data.md +++ b/doc/user/tutorials/interacting-with-geospatial-data.md @@ -44,6 +44,8 @@ as geospatial metadata and overviews/tile pyramids. Fig. 5: Example of a **Raster** data layer in QGreenland, ice sheet velocity, where each grid cell in the raster is 500 m x 500 m and is color-coded by a velocity + +(interacting-with-geospatial-data-layer-properties)= ## Layer Properties Right clicking on a data layer in the **Layers Panel** and selecting ‘Properties’, or simply double