Add command line docs

qupath · Jun 3, 2020 · f06c5c6 · f06c5c6
1 parent 9d4f6a5
commit f06c5c6
Show file tree

Hide file tree

Showing 7 changed files with 81 additions and 11 deletions.
diff --git a/docs/advanced/command_line.rst b/docs/advanced/command_line.rst
@@ -0,0 +1,70 @@
+************
+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:
+
+.. code-block:: 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.
+
+.. code-block:: bash
+
+  "QuPath-0.2.0 (console).exe" --help
+
+.. figure:: images/command_line_win.png
+  :align: center
+  :width: 80%
+  :class: shadow-image
+
+Mac
+===
+
+On macOS, the executable is buried inside the ``.app`` file and therefore you need something like:
+
+.. code-block:: 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.
+
+.. code-block:: bash
+
+  QuPath-0.2.0 script --help
+
+.. figure:: images/command_line_mac_script.png
+  :align: center
+  :width: 95%
diff --git a/docs/advanced/images/command_line_mac.png b/docs/advanced/images/command_line_mac.png
diff --git a/docs/advanced/images/command_line_mac_script.png b/docs/advanced/images/command_line_mac_script.png
diff --git a/docs/advanced/images/command_line_win.png b/docs/advanced/images/command_line_win.png
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -9,3 +9,4 @@ Advanced
   exporting_images
   exporting_annotations
   stardist
+  command_line
diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst
@@ -19,6 +19,15 @@ Download QuPath for your platform (Windows, Linux, macOS) from `GitHub <https://
   Recent security changes in Windows and macOS are likely to complicate installation slightly. |br|
   See :ref:`Troubleshooting` for more information.
 
+.. admonition:: What is *QuPath (console).exe*?
+
+  On Windows, you will see two executable files: *QuPath.exe* and *QuPath (console).exe* -- perhaps with version numbers incorporated.
+
+  You can use either.
+  The only difference between these is that the *console* version also shows a console that prints text as QuPath runs.
+  This is useful when using the :ref:`Command line`.
+
+
 =============
 Setup options
 =============

diff --git a/docs/reference/faqs.rst b/docs/reference/faqs.rst
@@ -184,17 +184,7 @@ You can change this to a fixed maximum size via the `-Xmx` Java option, e.g. to
 Can QuPath be run in batch mode from the command line?
 ======================================================
 
-Yes!
-The main priority remains the interactive application, but command line support was introduced in v0.2.0-m10.
-It will be further improved in the future.
-
-Accessing it on a Mac can be a little awkward; something like this should work (after adapting for version number):
-
-.. code-block:: bash
-
-  ./QuPath-0.2.0.app/Contents/MacOS/QuPath-0.2.0 --help
-  
-
+Yes! See :ref:`Command line`.
 
 
 Why does QuPath recommend using US English settings on startup?