Improve the developer quickstart documentation (#1144)

* Improve the developer quickstart documentation and remove obsolete instructions.

* * Clarification of the different C++ code layers in the repo
* Remove usage of --user flag

docs/tutorials/quickstart.md

@@ -2,18 +2,20 @@
 
 This is for users who wish to get started using the "OTIOView" application to inspect the contents of editorial timelines.
 
+**Note** This guide assumes that you are working inside a [virtualenv](https://virtualenv.pypa.io/en/latest/).
+
 ## Install Prerequisites
 
 OTIOView has an additional prerequisite to OTIO:
 
-- Try `pip install PySide2`
+- Try `python -m pip install PySide2`
 - If that doesn't work, try downloading PySide2 here: <a href="https://wiki.qt.io/Qt_for_Python" target="_blank">https://wiki.qt.io/Qt_for_Python</a>
 
 You probably want the prebuilt binary for your platform.  PySide2 generally includes a link to the appropriate version of Qt as well.
 
 ## Install OTIO
 
-- `pip install opentimelineio`
+- `python -m pip install opentimelineio`
 
 ## Configure Environment Variables for extra adapters
 
@@ -31,6 +33,10 @@ Once you have pip installed OpenTimelineIO, you should be able to run:
 Get the source and submodules:
 + `git clone [email protected]:PixarAnimationStudios/OpenTimelineIO.git`
 
+Before reading further, it is good to note that there is two parts to the
+C++ code: the OTIO C++ library that you can use in your C++ projects,
+and the C++ Python bindings that makes the C++ library available in Python.
+
 ## To build OTIO for C++ development:
 
 ### Linux/Mac
@@ -51,45 +57,42 @@ Get the source and submodules:
     cmake --build . --target install --config Release
 ```
 
-The CMAKE_INSTALL_PREFIX variable must be set to a path with no spaces in it, because CMake's default install location is in C:\Program Files, which won't work with OpenTimelineIO due to spaces in the path.
+The `CMAKE_INSTALL_PREFIX` variable must be set to a path with no spaces in it,
+because CMake's default install location is in `C:\Program Files`, which won't work
+with OpenTimelineIO due to spaces in the path.
 
 ## To build OTIO for Python development:
 
-### Linux
-
-+ `python setup.py install`
-
-### Mac
-
-+ `python setup.py install --user`
-
-The `--user` option is not necessary if the build is done within a virtualenv.
-
-### Windows - in an "x64 Native Tools Command Prompt" for Visual Studio
-
-+ `python setup.py install --cxx-install-root=C:/path/to/install/cpp`
++ `python -m pip install .`
 
 ## To build OTIO for both C++ and Python development:
 
-The first time setup.py is run, cmake scripts will be created, and the headers and libraries will be installed where you specify. If the C++ or Python  sources are subsequently modified, running this command again will build and update everything appropriately.
-
-**Note** Any CMake arguments can be passed through `python setup.py install` or `pip` by using the CMAKE_ARGS environment variable.  *nix Example:
-
-`env CMAKE_ARGS="-DCMAKE_VAR=VALUE1 -DCMAKE_VAR_2=VALUE2" pip install .`
+The Python package is a mix of pure python and C++ code. Therefore, it is
+recommended to use the python tooling (`python -m pip`) to develop both
+the C++ binding and the pure python code. We use `setuptools` as our
+python build backend, which means `pip` will call the `setup.py` in the root
+of the directory to build both the pure python and the C++ bindings.
+`setuptools` will take care of all the complexity of building a C++ Python
+extension for you.
 
-### Linux
+The first time `setup.py` is run, cmake scripts will be created, and the headers
+and libraries will be installed where you specify. If the C++ or Python  sources
+are subsequently modified, running this command again will build and update everything
+appropriately.
 
-+ `python setup.py install --cxx-install-root=/home/someone/cxx-otio-root`
+**Note** Any CMake arguments can be passed through `pip` by using the `CMAKE_ARGS`
+environment variable when building from source. *nix Example:
 
-### Mac
-
-+ `python setup.py install --cxx-install-root=/home/someone/cxx-otio-root --user`
-
-The `--user` option is not necessary if the build is done within a virtualenv.
-
-### Windows - in an "x64 Native Tools Command Prompt" for Visual Studio
+```bash
+env CMAKE_ARGS="-DCMAKE_VAR=VALUE1 -DCMAKE_VAR_2=VALUE2" python -m pip install .
+```
 
-+ `python setup.py install --cxx-install-root=C:/path/to/install/cpp`
+`python -m pip install .` adds some overhead that might be annoying or unwanted when
+developing the python bindings. For that reason (and only that reason), if you want a faster
+iteration process, you can use `setuptools` commands. For example you can use
+`python setup.py build_ext` to only run the compilation step. Be aware that calling `setup.py`
+directly is highly discouraged and should only be used when no of the other options
+are viable. See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html.
 
 To compile your own C++ file referencing the OTIO headers from your C++ build using gcc or clang, add the following -I flags:
 
@@ -105,9 +108,8 @@ To use opentime without opentimelineio, link with -lopentime instead, and compil
 
 ### Linux / GDB / LLDB
 
-From your virtual environment, compile with debug flags:
-
-+ `env OTIO_CXX_DEBUG_BUILD=1 python setup.py install`
+To compile in debug mode, set the `OTIO_CXX_DEBUG_BUILD` environment variable to any value
+and then `python -m pip install`.
 
 You can then attach GDB to python and run your program:
 
@@ -133,8 +135,12 @@ GDB will automatically break when it hits the SIGINT line.
 
 The doxygen docs can be generated with the following commands: 
 
-`cd doxygen ; doxygen config/dox_config ; cd ..`
+```
+cd doxygen ; doxygen config/dox_config ; cd ..
+```
 
 Another option is to trigger the make target: 
 
-`make doc-cpp`
+```
+make doc-cpp
+```