Add even more images.

Author: tobiasraabe

docs/source/_static/images/how-to-capture-output.png

@@ -46,11 +46,11 @@ You can influence output capturing mechanisms from the command line:
 
 .. code-block:: console
 
-    pytask -s                  # disable all capturing
-    pytask --capture=sys       # replace sys.stdout/stderr with in-mem files
-    pytask --capture=fd        # also point filedescriptors 1 and 2 to temp file
-    pytask --capture=tee-sys   # combines 'sys' and '-s', capturing sys.stdout/stderr
-                               # and passing it along to the actual sys.stdout/stderr
+    $ pytask -s                  # disable all capturing
+    $ pytask --capture=sys       # replace sys.stdout/stderr with in-mem files
+    $ pytask --capture=fd        # also point filedescriptors 1 and 2 to temp file
+    $ pytask --capture=tee-sys   # combines 'sys' and '-s', capturing sys.stdout/stderr
+                                 # and passing it along to the actual sys.stdout/stderr
 
 
 Using print statements for debugging
@@ -75,24 +75,4 @@ print statements for debugging:
 and running this module will show you precisely the output of the failing function and
 hide the other one:
 
-.. code-block:: console
-
-    $ pytask -s
-    ========================= Start pytask session =========================
-    Platform: win32 -- Python 3.x.x, pytask 0.x.x, pluggy 0.13.x
-    Root: .
-    Collected 2 task(s).
-
-    F.
-    =============================== Failures ===============================
-    _________________ Task task_capture.py::task_func2 failed ______________
-
-    Traceback (most recent call last):
-      File "task_capture.py", line 7, in task_func2
-        assert False
-    AssertionError
-
-    ---------------------- Captured stdout during call ---------------------
-    Debug statement.
-
-    ==================== 1 succeeded, 1 failed in 0.01s ====================
+.. image:: /_static/images/how-to-capture-output.png

docs/source/_static/images/how-to-debug-pdb.png

@@ -12,24 +12,19 @@ Tracebacks
 ----------
 
 You can enrich the display of tracebacks by showing local variables in each stack frame.
-Just execute pytask with
+Just execute pytask with :confval:`show_locals`, meaning ``pytask --show-locals``.
 
-.. code-block:: console
-
-    $ pytask --show-locals
+.. image:: /_static/images/how-to-debug-show-locals.png
 
 
 Debugging
 ---------
 
-Running
-
-.. code-block:: console
+Using :confval:`pdb` enables the post-mortem debugger. Whenever an exception is raised
+inside a task, the prompt will enter the debugger enabling you to find out the cause of
+the exception.
 
-    $ pytask --pdb
-
-enables the post-mortem debugger. Whenever an exception is raised inside a task, the
-prompt will enter the debugger enabling you to discover the source of the exception.
+.. image:: /_static/images/how-to-debug-pdb.png
 
 .. seealso::
 
@@ -46,11 +41,9 @@ prompt will enter the debugger enabling you to discover the source of the except
 Tracing
 -------
 
-If you want to enter the debugger at the start of every task, use
-
-.. code-block:: console
+If you want to enter the debugger at the start of every task, use :confval:`trace`.
 
-    $ pytask --trace
+.. image:: /_static/images/how-to-debug-trace.png
 
 
 Custom debugger

docs/source/_static/images/how-to-debug-show-locals.png

@@ -4,9 +4,9 @@ How to write a task
 Starting from the project structure in the :doc:`previous tutorial
 <how_to_set_up_a_project>`, this tutorial teaches you how to write your first task.
 
-The task will be defined in ``src/task_data_preparation.py`` and it will generate
-artificial data which will be stored in ``bld/data.pkl``. We will call the function in
-the module :func:`task_create_random_data`.
+The task will be defined in ``src/my_project/task_data_preparation.py`` and it will
+generate artificial data which will be stored in ``bld/data.pkl``. We will call the
+function in the module :func:`task_create_random_data`.
 
 .. code-block::
 
@@ -33,7 +33,7 @@ Here, we define the function
 
     import pytask
     import numpy as np
-    import pandas as np
+    import pandas as pd
 
     from my_project.config import BLD
 
@@ -57,31 +57,15 @@ To let pytask track the product of the task, you need to use the
     You learn more about adding dependencies and products to a task in the next
     :doc:`tutorial <how_to_define_dependencies_products>`.
 
-To execute the task, type the following command in your shell.
+Now, execute pytask which will automatically collect tasks in the current directory and
+subsequent directories.
 
-.. code-block:: console
-
-    $ pytask task_data_preparation.py
-    ========================= Start pytask session =========================
-    Platform: linux -- Python 3.x.y, pytask 0.x.y, pluggy 0.x.y
-    Root: xxx
-    Collected 1 task(s).
-
-    .
-    ======================= 1 succeeded in 1 second ========================
-
-Executing
-
-.. code-block:: console
-
-    $ pytask
-
-would collect all tasks in the current working directory and in all subsequent folders.
+.. image:: /_static/images/how-to-write-a-task.png
 
 .. important::
 
-    By default, pytask assumes that tasks are functions in modules whose names are both
-    prefixed with ``task_``.
+    By default, pytask assumes that tasks are functions and both, the function name and
+    the module name, must be prefixed with ``task_``.
 
     Use the configuration value :confval:`task_files` if you prefer a different naming
     scheme for the task modules.