[Console] Create consistent console screenshots

Author: wouterj

_images/components/console/completion.gif

@@ -1,8 +1,8 @@
-How to Create Symfony Diagrams
-==============================
+How to Create Symfony Images
+============================
 
-Creating the Diagram
---------------------
+Creating Diagrams
+-----------------
 
 * Use [Dia][1] as the diagramming application;
 * Use [PT Sans Narrow][2] as the only font in all diagrams (if possible, use
@@ -21,8 +21,7 @@ Creating the Diagram
 In case of doubt, check the existing diagrams or ask to the
 [Symfony Documentation Team][3].
 
-Saving and Exporting the Diagram
---------------------------------
+### Saving and Exporting the Diagram
 
 * Save the original diagram in `*.dia` format in `_images/sources/<folder-name>`;
 * Export the diagram to SVG format and save it in `_images/<folder-name>`.
@@ -33,8 +32,7 @@ that transforms text into vector shapes (resulting file is larger in size, but
 it's truly portable because text is displayed the same even if you don't have
 some fonts installed).
 
-Including the Diagram in the Symfony Docs
------------------------------------------
+### Including the Diagram in the Symfony Docs
 
 Use the following snippet to embed the diagram in the docs:
 
@@ -44,21 +42,57 @@ Use the following snippet to embed the diagram in the docs:
     <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
 ```
 
-Reasoning
----------
+### Reasoning
 
 * Dia was chosen because it's one of the few applications which are free, open
   source and compatible with Linux, macOS and Windows.
 * Font, colors and line widths were chosen to be similar to the diagrams used
   in the best tech books.
 
-Troubleshooting
----------------
+### Troubleshooting
 
 * On some macOS systems, Dia cannot be executed as a regular application and
   you must run the following console command instead:
   `export DISPLAY=:0 && /Applications/Dia.app/Contents/Resources/bin/dia`
 
+Creating Console Screenshots
+----------------------------
+
+* Use [Asciinema][4] to record the console session locally:
+
+  ```
+  $ asciinema rec -c bash recording.cast
+  ```
+* Use `$ ` as the prompt in recordings. E.g. if you're using Bash, add the
+  following lines to your ``.bashrc``:
+
+  ```
+  if [ "$ASCIINEMA_REC" = "1" ]; then
+    PS1="\e[37m$ \e[0m"
+  fi
+  ```
+* Save the generated asciicast in `_images/sources/<folder-name>`.
+
+### Rendering the Recording
+
+Rendering the recording can be a difficult task. The [documentation team][3]
+is always ready to help you with this task (e.g. you can open a PR with
+only the asciicast file).
+
+* Use [agg][5] to generated a GIF file from the recording;
+* Use the ``_images/sources/ascii-render.sh`` file to call agg:
+
+  ```
+  AGG_PATH=/path/to/agg ./_images/sources/ascii-render.sh recording.cast --cols 45 --rows 20
+  ```
+
+  This utility configures a predefined theme;
+* Always configure `--cols`` (width) and ``--rows`` (height), try to use as
+  low as possible numbers. Do not exceed 70 columns;
+* Save the generated GIF file in `_images/<folder-name>`.
+
 [1]: http://dia-installer.de/
 [2]: https://fonts.google.com/specimen/PT+Sans+Narrow
 [3]: https://symfony.com/doc/current/contributing/code/core_team.html
+[4]: https://github.com/asciinema/asciinema
+[5]: https://github.com/asciinema/agg

_images/components/console/cursor.gif

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+case "$1" in
+    ''|help|-h)
+        echo "ansi-render.sh RECORDING [options]"
+        echo ""
+        echo "  RECORDING: path to the .cast file generated by asciinema"
+        echo "  [options]: optional options to be passed to agg"
+        ;;
+    *)
+        recording=$1
+        extra_options=
+        if [ $# -gt 1 ]; then
+            shift
+            extra_options=$@
+        fi
+
+        #   --theme 1f2937,f9fafb,8b949e,ff7b72,7ee787,ffa657,79c0ff,d2a8ff,a5d6ff,8b949e \
+        #                                       1f4631
+        #   --cols 92 --rows 10
+        ${AGG_PATH:-agg} \
+            --theme 18202a,f9fafb,f9fafb,ff7b72,1f4631,ffa657,79c0ff,d2a8ff,a5d6ff,f9fafb,8b949e,ff7b72,00c300,ffa657,79c0ff,d2a8ff,a5d6ff,f9fafb --line-height 1.6 \
+            $extra_options \
+            $recording $(echo $recording | sed "s/cast/gif/")
+        ;;
+esac

_images/components/console/process-helper-debug.png

@@ -0,0 +1,37 @@
+{"version": 2, "width": 76, "height": 30, "timestamp": 1663253713, "env": {"SHELL": "/usr/bin/fish", "TERM": "st-256color"}}
+[0.00798, "o", "\u001b[?2004h\u001b[90m$ \u001b[0m"]
+[0.614685, "o", "b"]
+[0.776549, "o", "i"]
+[0.86682, "o", "n"]
+[1.092426, "o", "/"]
+[1.332671, "o", "c"]
+[1.55068, "o", "o"]
+[1.630651, "o", "n"]
+[1.784584, "o", "s"]
+[1.873108, "o", "o"]
+[2.074652, "o", "l"]
+[2.180433, "o", "e"]
+[2.260475, "o", " "]
+[2.696628, "o", "\u0007"]
+[2.947263, "o", "\r\nabout                       debug:event-dispatcher\r\nassets:install              debug:router\r\ncache:clear                 help\r\ncache:pool:clear            lint:container\r\ncache:pool:delete           lint:yaml\r\ncache:pool:list             list\r\ncache:pool:prune            router:match\r\ncache:warmup                secrets:decrypt-to-local\r\ncompletion                  secrets:encrypt-from-local\r\nconfig:dump-reference       secrets:generate-keys\r\ndebug:autowiring            secrets:list\r\ndebug:config                secrets:remove\r\ndebug:container             secrets:set\r\ndebug:dotenv                \r\n\u001b[37m$ \u001b[0mbin/console "]
+[3.614479, "o", "s"]
+[3.802449, "o", "e"]
+[4.205631, "o", "\u0007crets:"]
+[4.520435, "o", "r"]
+[4.598031, "o", "e"]
+[5.026287, "o", "move "]
+[5.47041, "o", "\u0007SOME_"]
+[5.673941, "o", "\u0007"]
+[6.024086, "o", "\r\nSOME_OTHER_SECRET  SOME_SECRET        \r\n\u001b[37m$ \u001b[0mbin/console secrets:remove SOME_"]
+[6.770627, "o", "O"]
+[7.14335, "o", "THER_SECRET "]
+[7.724482, "o", "\r\n\u001b[?2004l\r"]
+[7.776657, "o", "\r\n"]
+[7.779108, "o", "\u001b[30;42m                                                                            \u001b[39;49m\r\n\u001b[30;42m [OK] Secret \"SOME_OTHER_SECRET\" removed from \"config/secrets/dev/\".        \u001b[39;49m\r\n\u001b[30;42m                                                                            \u001b[39;49m\r\n\r\n"]
+[7.782993, "o", "\u001b[?2004h\u001b[37m$ \u001b[0m"]
+[9.214537, "o", "e"]
+[9.522429, "o", "x"]
+[9.690371, "o", "i"]
+[9.85446, "o", "t"]
+[10.292412, "o", "\r\n\u001b[?2004l\r"]
+[10.292526, "o", "exit\r\n"]

_images/components/console/process-helper-error-debug.png

@@ -0,0 +1,49 @@
+{"version": 2, "width": 191, "height": 30, "timestamp": 1663251833, "env": {"SHELL": "/usr/bin/fish", "TERM": "st-256color"}}
+[0.007941, "o", "\u001b[?2004h\u001b[90m$ \u001b[0m"]
+[0.566363, "o", "c"]
+[0.643353, "o", "l"]
+[0.762325, "o", "e"]
+[0.952363, "o", "a"]
+[0.995878, "o", "r"]
+[1.107784, "o", "\r\n\u001b[?2004l\r"]
+[1.109766, "o", "\u001b[H\u001b[2J"]
+[1.109946, "o", "\u001b[?2004h\u001b[30m$ \u001b[0m"]
+[1.653461, "o", "p"]
+[1.772323, "o", "h"]
+[1.856444, "o", "p"]
+[1.980339, "o", " "]
+[2.15827, "o", "c"]
+[2.273242, "o", "u"]
+[2.402231, "o", "r"]
+[2.563066, "o", "s"]
+[2.760266, "o", "o"]
+[2.900252, "o", "r"]
+[3.020537, "o", "."]
+[3.316404, "o", "p"]
+[3.403213, "o", "h"]
+[3.483391, "o", "p"]
+[3.820273, "o", "\r\n\u001b[?2004l\r"]
+[3.845697, "o", "\u001b[6;9H#"]
+[4.045942, "o", "\u001b[8;9H#"]
+[4.246327, "o", "\u001b[8;2H#####"]
+[4.446737, "o", "\u001b[2;9H#######"]
+[4.647128, "o", "\u001b[7;7H#"]
+[4.84749, "o", "\u001b[3;9H#"]
+[5.047857, "o", "\u001b[7;9H#"]
+[5.248246, "o", "\u001b[4;9H#"]
+[5.448622, "o", "\u001b[2;2H#####"]
+[5.648999, "o", "\u001b[3;7H#"]
+[5.849378, "o", "\u001b[5;9H#####"]
+[6.049711, "o", "\u001b[3;1H#"]
+[6.250118, "o", "\u001b[7;1H#"]
+[6.45056, "o", "\u001b[5;2H#####"]
+[6.650897, "o", "\u001b[4;1H#"]
+[6.851281, "o", "\u001b[6;7H#"]
+[7.051644, "o", "\u001b[9;1H"]
+[7.058802, "o", "\u001b[?2004h\u001b[30m$ \u001b[0m"]
+[7.657612, "o", "e"]
+[7.846956, "o", "x"]
+[7.949451, "o", "i"]
+[8.0893, "o", "t"]
+[8.201144, "o", "\r\n\u001b[?2004l\r"]
+[8.201227, "o", "exit\r\n"]