From cec8d15b4662ff02cd1d60e8d5437f38fcf22fdf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= <gina@octoprint.org>
Date: Wed, 29 Nov 2017 19:15:01 +0100
Subject: [PATCH] Some additions to the docs

  * Note that api/job is what you want for info about the selected file
    as promised in #2251
  * Added pause/resume script from
    https://gist.github.com/foosel/1c09e269b1c0bb7a471c20eef50c8d3e
    as example to the gcode scripts section (with disclaimer)
---
 docs/api/job.rst                |  3 ++
 docs/features/gcode_scripts.rst | 69 +++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/docs/api/job.rst b/docs/api/job.rst
index 5d727228..338a10ea 100644
--- a/docs/api/job.rst
+++ b/docs/api/job.rst
@@ -4,6 +4,9 @@
 Job operations
 **************
 
+Use these operations to query the currently selected file and start/cancel/restart/pause the
+actual print job.
+
 .. contents::
 
 .. _sec-api-jobs-command:
diff --git a/docs/features/gcode_scripts.rst b/docs/features/gcode_scripts.rst
index 9c12a35c..60cec42d 100644
--- a/docs/features/gcode_scripts.rst
+++ b/docs/features/gcode_scripts.rst
@@ -174,6 +174,75 @@ As you can see, the ``disable_hotends`` and ``disable_bed`` snippets utilize the
 extruders and set their temperature to 0, and to also set the bed temperature
 to 0 if a heated bed is configured.
 
+.. _sec-features-gcode_scripts-examples:
+
+Examples
+--------
+
+.. _sec-features-gcode_scripts-examples-more_nifty_pause_and_resume:
+
+More nifty pause and resume
+...........................
+
+If you do not have a multi-extruder setup, aren't printing from SD and have "Log position on pause" enabled under
+Settings > Serial > Advanced options, the following ``afterPrintPaused`` and
+``beforePrintResumed`` scripts might be interesting for you. With something like them in place, OctoPrint will move your print head
+out of the way to a safe rest position (here ``G1 X0 Y0``, you might want to adjust that) on pause and move it back
+to the persisted pause position on resume, making sure to also reset the extruder and feedrate.
+
+.. code-block:: jinja
+   :caption: ``afterPrintPaused`` script
+
+   {% if pause_position.x is not none %}
+   ; relative XYZE
+   G91
+   M83
+
+   ; retract filament, move Z slightly upwards
+   G1 Z+5 E-5 F4500
+
+   ; absolute XYZE
+   M82
+   G90
+
+   ; move to a safe rest position, adjust as necessary
+   G1 X0 Y0
+   {% endif %}
+
+.. code-block:: jinja
+   :caption: ``beforePrintResumed`` script
+
+   {% if pause_position.x is not none %}
+   ; relative extruder
+   M83
+
+   ; prime nozzle
+   G1 E-5 F4500
+   G1 E5 F4500
+   G1 E5 F4500
+
+   ; absolute E
+   M82
+
+   ; absolute XYZ
+   G90
+
+   ; reset E
+   G92 E{{ pause_position.e }}
+
+   ; move back to pause position XYZ
+   G1 X{{ pause_position.x }} Y{{ pause_position.y }} Z{{ pause_position.z }} F4500
+
+   ; reset to feed rate before pause if available
+   {% if pause_position.f is not none %}G1 F{{ pause_position.f }}{% endif %}
+   {% endif %}
+
+.. warning::
+
+   As mentioned in the warning above and the description of the example itself, this will *only* work if you are
+   not printing from SD and not using multiple extruders since OctoPrint will only then be able to track the
+   necessary position data and print parameters due to firmware limitations.
+
 .. seealso::
 
    `Jinja Template Designer Documentation <http://jinja.octoprint.org/templates.html>`_