Merge pull request #47 from petebankhead/0.4

Convert docs to markdown

.gitignore

@@ -1 +1,3 @@
+.DS_Store
+
 _build/**

conf.py

@@ -19,7 +19,7 @@
 
 project = 'QuPath'
 copyright = '2019-2022, QuPath docs authors'
-author = 'QuPath docs authors'
+author = 'QuPath authors'
 
 
 # -- General configuration ---------------------------------------------------
@@ -72,18 +72,100 @@
 .. |br| raw:: html
 
   <br/>
-  
+
 .. |vertical_ellipsis| unicode:: 0x22EE
 
 .. |copyright| unicode:: 0xA9
 """
 
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+#    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
 
 highlight_language = 'groovy'
 
 html_logo = 'docs/images/qupath_128.png'
 
 html_favicon = 'docs/images/QuPath.ico'
 
-release = '0.4.0-SNAPSHOT'
+release = '0.4.0'
 version = '0.4a1'
+
+myst_substitutions = {
+
+  "rectangle": '<img src="../images/icons/Rectangle.png" />',
+  "icon_rectangle": '<img src="../images/icons/Rectangle.png" class="inline-icon" />',
+
+  "ellipse": '<img src="../images/icons/Ellipse.png" />',
+  "icon_ellipse": '<img src="../images/icons/Ellipse.png" class="inline-icon" />',
+
+  "line": '<img src="../images/icons/Line.png" />',
+  "icon_line": '<img src="../images/icons/Line.png" class="inline-icon" />',
+
+  "polygon": '<img src="../images/icons/Polygon.png" />',
+  "icon_polygon": '<img src="../images/icons/Polygon.png" class="inline-icon" />',
+
+  "brush": '<img src="../images/icons/Brush.png" />',
+  "icon_brush": '<img src="../images/icons/Brush.png" class="inline-icon" />',
+
+  "wand": '<img src="../images/icons/Wand.png" />',
+  "icon_wand": '<img src="../images/icons/Wand.png" class="inline-icon" />',
+
+  "points": '<img src="../images/icons/Points.png" />',
+  "icon_points": '<img src="../images/icons/Points.png" class="inline-icon" />',
+
+  "move": '<img src="../images/icons/Move.png" />',
+  "icon_move": '<img src="../images/icons/Move.png" class="inline-icon" />',
+
+  "grid": '<img src="../images/icons/Grid.png" />',
+  "icon_grid": '<img src="../images/icons/Grid.png" class="inline-icon" />',
+
+  "measure": '<img src="../images/icons/Measure.png" />',
+  "icon_measure": '<img src="../images/icons/Measure.png" class="inline-icon" />',
+
+  "table": '<img src="../images/icons/Table.png" />',
+  "icon_table": '<img src="../images/icons/Table.png" class="inline-icon" />',
+
+  "cog": '<img src="../images/icons/Cog.png" />',
+  "icon_cog": '<img src="../images/icons/Cog.png" class="inline-icon" />',
+
+  "annotations": '<img src="../images/icons/Annotations.png" />',
+  "icon_annotations": '<img src="../images/icons/Annotations.png" class="inline-icon" />',
+
+  "detections": '<img src="../images/icons/Detections.png" />',
+  "icon_detections": '<img src="../images/icons/Detections.png" class="inline-icon" />',
+
+  "annotations_fill": '<img src="../images/icons/Annotations_fill.png" />',
+  "icon_annotations_fill": '<img src="../images/icons/Annotations_fill.png" class="inline-icon" />',
+
+  "detections_fill": '<img src="../images/icons/Detections_fill.png" />',
+  "icon_detections_fill": '<img src="../images/icons/Detections_fill.png" class="inline-icon" />',
+
+  "tma_grid": '<img src="../images/icons/TMA_grid.png" />',
+  "icon_tma_grid": '<img src="../images/icons/TMA_grid.png" class="inline-icon" />',
+
+  "screenshot": '<img src="../images/icons/Screenshot.png" />',
+  "icon_screenshot": '<img src="../images/icons/Screenshot.png" class="inline-icon" />',
+
+  "extract_image": '<img src="../images/icons/Extract_image.png" />',
+  "icon_extract_image": '<img src="../images/icons/Extract_image.png" class="inline-icon" />',
+
+  "contrast": '<img src="../images/icons/Contrast.png" />',
+  "icon_contrast": '<img src="../images/icons/Contrast.png" class="inline-icon" />',
+
+  # "polyline": '<img src="../images/icons/Polyline.png" />',
+  # "icon_polyline": '<img src="../images/icons/Polyline.png" class="inline-icon" />',
+}

docs/advanced/command_line.md

@@ -0,0 +1,66 @@
+# Command line
+
+QuPath is *mostly* designed to be an interactive application, and this remains the main priority.
+
+However, v0.2.0 introduces a new command line, which makes it possible to:
+
+- Launch QuPath with specific options (e.g. a logging level)
+- Run scripts headlessly
+- Convert images to OME-TIFF
+
+:::{tip}
+The order in which command line arguments are passed can be important.
+See [this forum post](https://forum.image.sc/t/unexpected-command-line-usage-in-0-2-0-m10-and-greater/38548/2).
+:::
+
+## Viewing command line options
+
+The general way to view the command line options is with:
+
+```bash
+QuPath-0.2.0 --help
+```
+
+However, there are some platform-specific details on Windows and Mac.
+
+### Windows
+
+On Windows, there are two executable files for QuPath.
+It is necessary to use *"QuPath (console).exe"* here to be able to view the output, e.g.
+
+```bash
+"QuPath-0.2.0 (console).exe" --help
+```
+
+:::{figure} images/command_line_win.png
+:align: center
+:class: shadow-image
+:width: 80%
+:::
+
+### Mac
+
+On macOS, the executable is buried inside the `.app` file and therefore you need something like:
+
+```bash
+./QuPath-0.2.0.app/Contents/MacOS/QuPath-0.2.0 --help
+```
+
+:::{figure} images/command_line_mac.png
+:align: center
+:width: 95%
+:::
+
+## Subcommands
+
+Some of the command line functionality is available via *subcommands*, such as `script`.
+Help is available for these separately.
+
+```bash
+QuPath-0.2.0 script --help
+```
+
+:::{figure} images/command_line_mac_script.png
+:align: center
+:width: 95%
+:::