minor #17271 [Console] Create consistent console screenshots/recordings (wouterj)

This PR was merged into the 5.4 branch.

Discussion
----------

[Console] Create consistent console screenshots/recordings

The, honestly quite minor, issue with inconsistent terminal screenshots/recordings has been bugging me for quite some time. When creating the recording for my most recent console PR, I managed to get something set-up that can be replicated by others - although the rendering is a bit tricky.

The only remaining recording is the progress bar. At the moment, my terminal emulator crashes when displaying emoji's, so I have some trouble creating the asciicast file for it 😄

The color scheme is based on the dark theme terminal color scheme in the Symfony docs. I'm not totally convinced about the green color, which is too dark when used as foreground but the bright one is too light when used as background. If someone has a better suggestion, please let me know

Commits
-------

8bd5eef [Console] Create consistent console screenshots

Author: javiereguiluz

_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,59 @@ 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;
+* Install the [JetBrains Mono][6] font;
+* 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
+[6]: https://www.jetbrains.com/lp/mono/

_images/components/console/cursor.gif

@@ -0,0 +1,24 @@
+#!/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
+
+        # optionally, use this green color:     1f4631
+        ${AGG_PATH:-agg} \
+            --theme 18202a,f9fafb,f9fafb,ff7b72,7ee787,ffa657,79c0ff,d2a8ff,a5d6ff,f9fafb,8b949e,ff7b72,00c300,ffa657,79c0ff,d2a8ff,a5d6ff,f9fafb --line-height 1.6 \
+            --font-family 'JetBrains Mono' \
+            $extra_options \
+            $recording $(echo $recording | sed "s/cast/gif/")
+        ;;
+esac