[pitivi] docs: Add `Debugging Pitivi` section

[Alexandru Băluț <alexbalut src gnome org>]

commit 330d34b572ec2f475fe49ca5cf13774e4a574cb0
Author: Piotrek Brzeziński <thewildtree outlook com>
Date:   Tue Apr 20 22:09:07 2021 +0200

    docs: Add `Debugging Pitivi` section

 bin/pitivi.in     |  6 ++++++
 docs/Debugging.md | 35 +++++++++++++++++++++++++++++++++++
 docs/HACKING.md   |  6 +++---
 docs/sitemap.txt  |  1 +
 4 files changed, 45 insertions(+), 3 deletions(-)
---
diff --git a/bin/pitivi.in b/bin/pitivi.in
index 5dd359f84..322d903b6 100755
--- a/bin/pitivi.in
+++ b/bin/pitivi.in
@@ -142,6 +142,12 @@ def _check_requirements():
 def _run_pitivi():
     from pitivi import application
 
+    if os.environ.get("PITIVI_VSCODE_DEBUG", False):
+        import debugpy
+        debugpy.listen(5678)
+        print("Waiting for the debugger to attach...")
+        debugpy.wait_for_client()
+
     signal.signal(signal.SIGINT, signal.SIG_DFL)
     app = application.Pitivi()
     app.run(sys.argv)
diff --git a/docs/Debugging.md b/docs/Debugging.md
new file mode 100644
index 000000000..d724fcc56
--- /dev/null
+++ b/docs/Debugging.md
@@ -0,0 +1,35 @@
+## Debugging
+
+To debug Pitivi, you need an IDE with the ability to attach its debugger to a
+remote process. Out of the box, Pitivi supports the debugger used in
+[VS Code](https://code.visualstudio.com/docs/python/debugging#_local-script-debugging),
+but it can be modified to work with the Professional version of
+[PyCharm](https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html#remote-debug-config),
+for example.
+
+### Visual Studio Code
+
+Assuming you have already installed the
+[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python),
+install `debugpy` and open VS Code:
+
+```
+(ptv-flatpak) $ ptvenv python3 -m pip install --upgrade debugpy
+[...]
+(ptv-flatpak) $ code .
+```
+
+In VS Code, click the `Run and Debug` section on the left (or press
+Ctrl+Shift+D). Press `Create a launch.json file`, select `Python` and then
+`Remote Attach` from the list. Leave the hostname and port as default.
+
+The `launch.json` file should open afterwards with the generated
+configuration. Save the file and launch Pitivi with the `PITIVI_VSCODE_DEBUG` environment variable set to 1:
+
+```
+(ptv-flatpak) $ PITIVI_VSCODE_DEBUG=1 pitivi
+[...]
+Waiting for the debugger to attach...
+```
+
+Press `F5` in VS Code. If the Pitivi window shows up, your debugger is working.
diff --git a/docs/HACKING.md b/docs/HACKING.md
index 81f14ae88..aa7a92ba5 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -65,7 +65,7 @@ Hack away, and check the effect of your changes by simply running:
 ```
 
 
-### Updating the development environment
+## Updating the development environment
 
 To update the dependencies installed in the sandbox, run:
 ```
@@ -103,7 +103,7 @@ to be built with `build`, to regenerate the corresponding `.py` files.
 with `binstall`. See "Switching locales" below.
 
 
-### Hacking on Pitivi dependencies (Meson)
+## Hacking on Pitivi dependencies (Meson)
 
 If you have to work on say, [GStreamer Editing 
Services](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
 which is built using the Meson build system, first clone it into your
@@ -138,7 +138,7 @@ Also beware that it will not take into account not committed
 changes.
 
 
-### Hacking on Pitivi dependencies (Autotools, Make, etc)
+## Hacking on Pitivi dependencies (Autotools, Make, etc)
 
 If the project you are working on is built with other tools, make sure
 they are run in the sandbox by using `ptvenv`. For example:
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 1ad591e6c..1be0dc6cb 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -9,6 +9,7 @@ index.md
                Coding_style_guide.md
                Command_line_tools.md
                Inspecting_UI.md
+               Debugging.md
        Testing.md
                QA_Scenarios.md
        Architecture.md