Add more details to user guide

Closes #224

HISTORY.md

@@ -1,6 +1,6 @@
 # History
 
-# 0.7.0 (2022-TBD)
+## 0.7.0 (2022-07-29)
 * Rebuilt UI from scratch using Qt
 * Build local taxon and observation database for partial online access and better performance
 * Build local taxon text search database for fully offline (and much faster) taxon autocomplete
@@ -12,7 +12,7 @@
 * Add GPS metadata
 * Many performance improvements, bugfixes, etc.
 
-# 0.6.0 (2021-06-16)
+## 0.6.0 (2021-06-16)
 * Improved image drag-and-drop, and support recursively adding images from subdirectories
 * Initial packaging with PyInstaller
 * Add tab for user-observed taxa
@@ -24,7 +24,7 @@
 * Update to Kivy 2
 * Improvements for docs, CI/project config, bugfixes, etc.
 
-# 0.5.0 (2020-06-03)
+## 0.5.0 (2020-06-03)
 * Add a full taxon search with filters and search results tab
 * Add tabs for recently viewed, frequently, viewed, and favorite taxa
 * Add context menus for local images
@@ -33,17 +33,17 @@
 * Add a Taxon data model
 * Performance improvements, bugfixes, etc.
 
-# 0.4.0 (2020-05-25)
+## 0.4.0 (2020-05-25)
 * Add scrollable list of taxon children and ancestors
 * Add caching for API requests and thumbnails
 * UI cleanup, bugfixes, docs
 
-# 0.3.0 (2020-05-24)
+## 0.3.0 (2020-05-24)
 * Add a taxon info display
 * Add a basic taxon name search with autocomplete
 
-# 0.2.0 (2020-05-19)
+## 0.2.0 (2020-05-19)
 * Add a basic GUI made with Kivy
 
-# 0.1.0 (2020-05-14)
+## 0.1.0 (2020-05-14)
 * Initial release; CLI tool with basic tagging functionality

README.md

@@ -24,37 +24,47 @@
 <!-- END-RTD-IGNORE -->
 
 ## Summary
-Naturtag is a tool for tagging image files with iNaturalist taxonomy & observation metadata.
-This includes a basic **command-line interface**, a work-in-progress **desktop application**,
-and can also be used as a **python library**.
+Naturtag is a tool for nature photographers that adds useful metadata to describe the organisms in
+your photos. It includes a **desktop application**, a **command-line interface**, and can also be
+used as a **python library**.
+
+It is mainly intended for use with [iNaturalist](https://www.inaturalist.org); it can tag your
+photos with either complete observation metadata, or just taxonomy metadata.
+
 
 ## Use Cases
-Naturtag takes useful information from your own iNaturalist observations and embeds it in your local
-photo collection, mainly using [XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) and
+Naturtag embeds this information in your local photo collection using
+[XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) and
 [EXIF](https://en.wikipedia.org/wiki/Exif) metadata. This has a variety of uses, including:
 
 ### Local photo organization
-If you like the way you can search and filter your observations on iNaturalist.org and its mobile
-apps, and you wish you could do that with your local photos, naturtag can help.
-It can tag your photos with **hierarchical keywords**, which can then be used in a photo viewer or
-DAM such as [**Lightroom**](https://millennialdiyer.com/articles/photography/lightroom-keyword-hierarchy/), [**FastPictureViewer**](https://www.fastpictureviewer.com), or
-[**XnViewMP**](https://www.xnview.com/en/xnviewmp).
+Naturtag can tag your photos with **hierarchical keywords** (aka structured keywords), which
+are supported by some photo viewers/editors like
+[**Lightroom**](https://millennialdiyer.com/articles/photography/lightroom-keyword-hierarchy/),
+[**FastPictureViewer**](https://www.fastpictureviewer.com),
+[**Photo Mechanic**](https://www.photometadata.org/META-Tutorials-Photo-Mechanic-Applying-Keywords),
+and [**XnViewMP**](https://www.xnview.com/en/xnviewmp).
 
 This essentially gives you a phylogenetic tree for browsing and filtering your photos.
-Example in XnView:
+
+<details>
+<summary><b>Example in XnView</b></summary>
 
 ![screenshot](assets/screenshots/xnview.png)
+</details>
 
 ### Photo hosting
 Naturtag can also simplify tagging photos for photo hosting sites like Flickr. For that use case, this
-tool generates structured keywords in the same format as
+tool generates semi-structured keywords in the same format as
 [iNaturalist's Flickr Tagger](https://www.inaturalist.org/taxa/flickr_tagger).
 
 Example search using these tags: https://www.flickr.com/photos/tags/taxonomy:class=arachnida
 
-Example of taxonomy tags on a Flickr photo page:
+<details>
+<summary><b>Example of taxonomy tags on Flickr</b></summary>
 
 ![screenshot](assets/screenshots/flickr.png)
+</details>
 
 
 ### Other biodiversity tools

docs/app.md

@@ -1,40 +1,78 @@
-# Application Guide
-The main interface for this project will be a desktop application, although it's still a work in
-progress. Soon this will be packaged into more convenient platform-specific builds, but for now it
-must be installed and launched from the command line.
+# {fa}`book` Application Guide
+This page describes how to use the main features of the Naturtag desktop application.
 
-To launch, run:
-```
-python -m naturtag.app.app
+Typically there will be three steps:
+1. {ref}`Select photos <selecting-images>`
+2. {ref}`Select an observation or species <selecting-metadata-source>`
+3. {ref}`Tag images <tagging-images>`
+
+```{note}
+Currently, the UI is meant for tagging one set of related photos at a time, but batch tagging
+features are planned for future updates.
 ```
 
-## Image Selection and Tagging
+(selecting-images)=
+## Selecting Images
 The **Photos** tab is the main interface for selecting and tagging images:
 
 ![Screenshot](../assets/screenshots/image-selector.png)
 
-1. Select images:
-    * Drag & drop images or folders into the window
-    * Or, select files via the file browser (from the toolbar, or `Ctrl+O`)
-2. Select iNaturalist metadata:
-    * Enter an iNaturalist observation ID or taxon ID
-    * Or paste an iNaturalist URLs with `Ctrl+V`
-    * Or search for a species from the **Species** tab (see details below)
-    * Coming soon: search for observations from the **Observations** tab
-3. Click the **Run** (▶️) button in the top right (or `Ctrl+R`) to tag the selected images
+To select images:
+* Drag & drop images or folders into the window
+* Select files with the {material-outlined}`add_photo_alternate` **Open** button in the toolbar (or `Ctrl+O`)
 
 Mouse actions:
 * **Left-click** an image for a fullscreen view
 * **Middle-click** an image to remove it
 * **Right-click** an image for a context menu with more actions:
 
+Use the {fa}`remove` button  in the toolbar (or `Ctrl+Shift+X`) to clear all selected images.
+
 ![Screenshot](../assets/screenshots/image-context-menu.png)
 
+(selecting-metadata-source)=
+## Selecting a Metadata Source
+Next, you will specify an observation or species to use as a metadata source
+There are a few ways to do this:
+* Paste an iNaturalist URL anywhere (with `Ctrl+V` or the {fas}`paste` **Paste** button from the toolbar)
+* Enter an iNaturalist observation ID or taxon ID
+* Use the {ref}`species-search` page
+
+(tagging-images)=
+## Tagging Images
+Once you have selected images and a metadata source, click the {fa}`play` **Run** button in the toolbar
+(or `Ctrl+R`) to generate and save image metadata.
+
+## Refreshing Metadata
+In many cases, you might upload an observation with only a rough identification (order, family,
+etc.), and later get a more specific (or corrected) ID on iNaturalist. In these cases, you can use
+the {fa}`refresh` **Refresh** button in the toolbar (or `F5`) to quickly update all of your selected images
+that have been previously tagged. When using Refresh, you can select images for multiple
+observations and taxa.
+
+Refresh has the following behavior depending on the metadata source:
+* For observations, this will update your image metadata with the latest observation details from
+iNaturalist, and fill in any additional missing information.
+* For taxa, this will update your image metadata with any missing taxonomy information (for example
+  if an image has been tagged with only a taxon ID)
+
+:::{note}
+If you would like to use a different tool to add taxon IDs to your photos, and then use Naturtag to
+fill in the rest of the details, you can add it as an EXIF or XMP keyword in the format:
+```
+taxon_id:12345
+```
+:::
+
+(species-search)=
 ## Species Search
 The **Species** tab contains tools to search and browse species to tag your images with:
 
 ![Screenshot](../assets/screenshots/taxon-search.png)
 
+This can be used to search for any taxonomic rank (genus, family, etc.), not just species.
+Elsewhere in the docs these will be referred to as **taxa** (singular: **taxon**).
+
 ### Basic Search
 You can start by searching by name, with autocompletion:
 
@@ -60,7 +98,7 @@ For example, a search for flies (_Diptera_) with 'ornate' in the name will look
 * **View on iNaturalist** will show more details about the taxon on inaturalist.org
 * Click on a taxon photo (or the thumbnails to the right) for a fullscreen view
 
-### Species Lists
+### Taxon Lists
 The additional tabs next to search results contain:
 * **Recent:** Recently viewed taxa
 * **Frequent:** Most frequently viewed taxa

docs/cli.md

@@ -1,8 +1,10 @@
 (cli)=
-# CLI
-This package provides the command `naturtag`, also aliased to `nt`. It takes an observation or
-species, plus some image files, and generates EXIF and XMP metadata to write to those images.
-You can see it in action here:
+# {fa}`terminal` CLI
+This page describes how to use the Naturtag CLI.
+
+The basic tagging features of naturtag can be used via the command `naturtag`, also aliased to `nt`.
+It takes an observation or species, plus some image files, and generates EXIF and XMP metadata to
+write to those images. You can see it in action here:
 [![asciicast](https://asciinema.org/a/0a6gzpt7AI9QpGoq0OGMDOxqi.svg)](https://asciinema.org/a/0a6gzpt7AI9QpGoq0OGMDOxqi)
 
 ## CLI Options
@@ -25,6 +27,13 @@ Options:
   --help                  Show this message and exit.
 ```
 
+## Metadata Options
+Some additional options are available to change which metadata formats to use.
+The CLI will use the same {ref}`app-settings` as the app, if available.
+
+You can also directly edit the config file at `settings.yml` in the naturtag data directory. The
+location varies by platform, and you can get this info from `naturtag --version`.
+
 ## Species & Observation IDs
 Either a species or observation may be specified, either by ID or URL.
 For example, all the following options will fetch the same taxonomy metadata:

docs/installation.md

@@ -1,12 +1,12 @@
-# Installation
+# {fa}`download` Installation
 Package downloads can be found on [GitHub Releases](https://github.com/pyinat/naturtag/releases).
 Platform-specific installation instructions are below:
 
 <!-- TODO: portable (.tar.gz) download links & instructions -->
 
 ```{warning}
 These packages and installers are brand new, and not yet throughly tested on all platforms.
-Please [create a bug report](https://github.com/pyinat/naturtag/issues/new) if you find any issues.
+Please [create a bug report](https://github.com/pyinat/naturtag/issues/new) if you find any issues!
 ```
 
 ::::{tab-set}

docs/metadata.md

@@ -1,7 +1,7 @@
-<!-- TODO: This is kind of a rough draft. Needs more editing. -->
+<!-- TODO: This is just a rough draft. Needs more details and editing. -->
 
 (metadata)=
-# Metadata
+# {fa}`code` Metadata
 This page describes the formats and types of metadata that naturtag generates.
 
 ## Metadata formats
@@ -22,15 +22,16 @@ may want to enable some of these formats but not others.
 
 ```{warning}
 After using naturtag, you can manually edit your image metadata using any other tool, but it's not
-recommended to use multiple tools to edit metadata for the same file.
+recommended to use multiple tools to edit metadata for the same file, if it contains multiple
+metadata formats.
 
 For example, some tools may use EXIF only, while others may use a combination of EXIF and XMP.
 ```
 
 ### Sidecar files
 A sidecar file can be saved alongside a photo that contains all XMP metadata.
-This has the advantage of not needing to modify the original image file, and
-also lets you associate the metadata with a RAW image file.
+This has the advantage of non-desctructive edits (not needing to modify the original image file),
+and also lets you associate the metadata with a RAW image file.
 
 The sidecar will have the same filename as the image, but with a `.xmp` extension. For example:
 ```bash

docs/reference.md

@@ -1,4 +1,4 @@
-# API Reference
+# {fa}`list` API Reference
 This section documents all the modules included in naturtag. Many of these are internal modules,
 and likely only relevant if you are interested in contributing to naturtag.
 

naturtag/metadata/meta_metadata.py

@@ -229,8 +229,8 @@ def simplify_keys(mapping: dict[str, str]) -> dict[str, str]:
     Simplify/deduplicate dict keys, to reduce variations in similarly-named keys
 
     Example::
-        >>> simplify_keys({'my_namepace:Super_Order': 'Panorpida'})
-        {'superfamily': 'Panorpida'}
+        >>> simplify_keys({'my_namepace:Sub_Family': 'Panorpinae'})
+        {'subfamily': 'Panorpinae'}
 
     Returns:
         dict with simplified/deduplicated keys