Update documentation (#84)

<!--
Thanks for your contribution! Please read this comment in its entirety.
It's quite important.
When a contributor merges the pull request, the title and the
description will be used to build the merge commit!

### Pull Request TITLE

It should be in the following format:

[ 12345: Summary of the changes made ] Where 12345 is the corresponding
Github Issue

OR

[ Summary of the changes made ] If it's solving something trivial, like
fixing a typo.
-->

### Linked issues
<!--
Link the Issue(s) this Pull Request is related to.

Each PR should link to at least one issue, in the form:

Use one line for each Issue. This allows auto-closing the related issue
when the fix is merged.

Fixes #12345
Fixes #54345
-->

[Build size because missing release variant in the docs](
#62)
[Missing --prefix to the install
step](#65)
[Missing --recursive flag while
cloning](#63)
### Summarize your change.

- Refresh the documentation to have all the full build steps in the main
README.md file with the common build aliases equivalent.

- Moves doc into docs.

### Describe the reason for the change.

- Blind spots in the OpenRV documentation cause multiple issues. 
- The documentation root folder should be named `docs,` as requested by
the documentation team for the future ReadTheDocs integration.

### Describe what you have tested and on which operating system.

- [ ] Windows aliases
- [ ] MacOS aliases
- [ ] Linux aliases
- [ ] Documentation link changes

### Add a list of changes and note any that might need special attention
during the review.

I updated the common build alias files to use `main_executable` instead
of a mix of `RV` and `rv`. This needs to be tested on all OSes.

I moved the doc folder to the docs folder. I think changed all
occurrences to `doc`, but it's to be double-checked.

### If possible, provide screenshots.

Main Readme Render: https://github.com/geffrak/OpenRV/tree/docs#readme
Windows setup doc Render:
https://github.com/geffrak/OpenRV/blob/docs/docs/build_system/config_windows.md
macOS setup doc Render:
https://github.com/geffrak/OpenRV/blob/docs/docs/build_system/config_macos.md
Linux setup doc Render:
https://github.com/geffrak/OpenRV/blob/docs/docs/build_system/config_linux_centos7.md

---------

Signed-off-by: Kerby Geffrard <kerby.geffrard@autodesk.com>

Author: geffrak

README.md

@@ -2,86 +2,174 @@
 Open RV is an image and sequence viewer for VFX and animation artists.
 Open RV is high-performant, hardware accelerated, and pipeline-friendly.
 
-## Documentation
-[RV Documentation](doc/rv-manuals.md)
+[RV Documentation](docs/rv-manuals.md)
 
-## Build Instructions
+## Cloning the repository
 
-You can build Open RV for Linux, Windows, and macOS. You build it from scratch using the instructions specific to each OS:
+OpenRV uses submodules to pull some dependencies. When cloning the repository, make sure to do it recursively by using the following command:
 
-* [Linux](doc/build_system/config_linux_centos7.md)
-* [Windows](doc/build_system/config_windows.md)
-* [macOS](doc/build_system/config_macos.md)
+```bash
+git clone --recursive https://github.com/AcademySoftwareFoundation/OpenRV.git
+```
+
+If you cloned the repo without setting the `--recursive` flag, you can initialize the submodule in another step with the following command:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Building the workstation
+
+Open RV is currently supported on the following operating systems:
+
+* [Windows 10 and 11](docs/build_system/config_windows.md)
+* [macOS Big Sur, Monterey and Ventura](docs/build_system/config_macos.md)
+* [Linux Centos 7](docs/build_system/config_linux_centos7.md)
+
+Support for other operating systems is on a best effort basis.
 
-### Building Tips
 
-#### Build Aliases
+## Building RV
 
 You can use `source rvmds.sh` to add common build aliases into your shell. After the first download following the installation of the required dependencies, use `rvbootstrap` to set up, configure, and build Open RV with the default options.
 
-After the setup, you can use `rvmk` to build.
+After the setup, you can use `rvmk` (the common build alias) to configure and build Open RV. You can also use `rvmkd` to configure and build in Debug.
 
-#### Compile in Parallel
+### Contributor setup
 
-Start the compilation in parallel by adding `--parallel[=threadCound]` to the build command. This is the same as using `-j`.
+This repository uses a pre-commit to execute formatting before a commit. To install the pre-commit hooks:
 
-#### 3rd Parties Outside Of Repository
+```shell
+pre-commit install
+```
 
-If you desire to keep your third-party builds between build cleanups, set `-DRV_DEPS_BASE_DIR=/path/to/third/party`.
 
-#### Expert Mode
 
-You can always go to the build directory and call the generator directly.
+### Cleanup
 
-## Running Open RV
+To clean your build directory and restart from a clean slate, use the `rvclean` common build alias, or delete the `_build` folder.
 
-Once the build ends, you can execute (or debug!) Open RV from the cmake-build directory.
 
-The path to the build is `cmake-build/stage/app`. The Open RV cmake options set up the environment so you can start the build without RPATH issues.
 
-## Install
+### Bootstrap
 
-The recommended method to install Open RV is to invoke the install build step tool using cmake.
+Before first your first Open RV build, you must install some python dependencies.
 
-The build system allows you to prepackage Open RV using cmake's install command and a prefix.
+#### Common build alias
 
-Then, it's up to you to either sign or package the result, or to do both. It should contain the minimum required to have a full Open RV.
+Use the `rvsetup` common build alias to run the bootstrap step.
 
-```shell
-cmake --install cmake-build --prefix /Absolute/path/to/a/destination/folder
+#### Manually
+
+```bash
+python3 -m pip install --user --upgrade -r requirements.txt
+```
+
+
+
+### Configure
+
+The project uses CMake and requires a `configure` step before building. It is during the configure step that you provide your Qt package.
+
+From the root of the repository, execute `cmake` and specify the path to an arbitrary build folder and the path to your QT5 package.
+
+#### Common build alias
+
+Use the `rvcfg` (the common build alias) to run the configuration step. You can also use `rvcfgd` to configure in Debug.
+
+#### Manually
+
+##### Windows
+
+On Windows, you must specify the path to Strawberry perl for the OpenSSL build.
+
+```bash
+cmake -B _build -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE=Release -DRV_DEPS_WIN_PERL_ROOT=/c/Strawberry/perl/bin -DRV_DEPS_QT5_LOCATION=/c/path/to/your/Qt/Root
 ```
 
-## Run Tests
+##### Linux and MacOS
+
+```bash
+cmake -B _build -DCMAKE_BUILD_TYPE=Release -DRV_DEPS_QT5_LOCATION=/Path/To/Your/Qt5/Root
+```
+
+#### Tips
+
+##### 3rd Parties Outside Of Repository
+
+To keep your third-party builds between build cleanups, set `-DRV_DEPS_BASE_DIR=/path/to/third/party`.
 
-You invoke Open RV tests with the following command:
+
+### Build
+
+Invoke the previously specified generator tool using cmake to run the `build` step (recommended).
+
+#### Common build alias
+
+Use the `rvbuild` (the common build alias) to run the build step. You can also use `rvbuildd` to build in Debug.
+
+#### Manually
+
+```bash
+cmake --build _build --config Release -v --parallel=8 --target main_executable
+```
+
+
+
+### Test
+
+Invoke the tests using ctest.
+
+#### Common build alias
+
+Use the `rvtest` common build alias to start the tests.
+
+#### Manually
 
 ```shell
-ctest --test-dir cmake-build --extra-verbose
+ctest --test-dir _build
 ```
 
-### Tests Tips
+#### Tips
 
-#### Run The Tests In Parallel
+##### Run The Tests In Parallel
 
-You can run the tests in parallel by specifying `--parallel X`, where X is the number of tests to run in parallel.
+You can run the `test` in parallel by specifying `--parallel X`, where X is the number of tests to run in parallel.
 
-#### Run A Subset Of The Tests
+##### Run A Subset Of The Tests
 
 You can apply a filter with the `-R` flag to specify a regex.
 
-#### Run The Tests Verbose
+##### Run The Tests Verbose
 
-You can run the tests with extra verbosity with the flag `--extra-verbose`. 
+You can run the tests with extra verbosity with the flag `--extra-verbose`.
 
 > **Important:** You cannot use `--extra-verbose` with `--parallel`. It's one or the other, not both.
 
-## Contributing to Open RV
 
-This repository uses pre-commit to have formatting executed before a commit. To install the hooks:
 
-```shell
-pre-commit install
-```
+### Run
+
+Once the build ends, you can execute (or debug!) Open RV from the _build directory.
+
+The path to the build is `_build/stage/app`. It contains everything required to have the proper debug symbols.
+
+
+
+### Install
 
-> **Important:** When the hooks reformat a file, you need to re-add them to git to have your `git commit` command executed.
-> Also, you can skip the hook execution by using `git commit -n`.
+Invoke the `install` step using cmake. The install step prepares Open RV for packaging by building a copy of Open RV in the `_install` folder.
+
+The build system allows you to prepackage Open RV using cmake's `install` command. It will strip debug symbols if required.
+
+Then, it's up to you to either sign or package the result, or to do both. It should contain the minimum required to have a functional Open RV.
+
+#### Common build alias
+
+Use the `rvinst` common build alias to install OpenRV.
+
+#### Manually
+
+```shell
+cmake --install _build --prefix _install
+```

cmake/macros/rv_stage.cmake

@@ -15,6 +15,7 @@ MACRO(ADD_SHARED_LIBRARY_LIST new_entry)
   )
 ENDMACRO()
 
+ADD_CUSTOM_TARGET(main_executable)
 ADD_CUSTOM_TARGET(executables)
 ADD_CUSTOM_TARGET(executables_with_plugins)
 ADD_CUSTOM_TARGET(shared_libraries)
@@ -614,6 +615,8 @@ FUNCTION(rv_stage)
       MESSAGE(FATAL_ERROR "\"${arg_TARGET}\" ${arg_TYPE} should be a EXECUTABLE, not a ${_native_target_type}")
     ENDIF()
 
+    ADD_DEPENDENCIES(main_executable ${arg_TARGET})
+
     IF(RV_TARGET_DARWIN)
       SET_TARGET_PROPERTIES(
         ${arg_TARGET}

doc/build_system/build_errors.md renamed to docs/build_system/build_errors.md

@@ -95,7 +95,7 @@ Call Stack (most recent call first):
 
 The newer Ubuntu, Centos & Rocky system usually won't have `python` out of the box, they have a `python3` interpreter.
 
-One solution is to instyall `pipenv` and start a local virtual environment. That will give you a `p[ython` command.
+One solution is to instyall `pipenv` and start a local virtual environment. That will give you a `python` command.
 
 ### (Linux)  pyconfig.h: No such file or directory
 

doc/build_system/config_linux_centos7.md renamed to docs/build_system/config_linux_centos7.md

@@ -8,8 +8,6 @@
 1. [Install CMake](#install-cmake)
 1. [Install nasm](#install-nasm)
 1. [Install Qt5](#install-qt)
-1. [Configure CMake](#configure)
-1. [Build Open RV](#build-including-incremental-builds)
 
 ## Install Basics
 
@@ -83,30 +81,4 @@ sudo make install
 
 Download the last version of Qt 5.15.x that you can get using the online installer on the [Qt page](https://www.qt.io/download-open-source). Logs, Android, iOS and WebAssembly are not required to build OpenRV.
 
-WARNING: If you decide fetch Qt from another source, make sure to build it with SSL support and that  it contains everything required to build PySide2 and that the file structure is similar to the official package.
-
-## Configure
-
-The project uses CMake and requires a configure step before building. It is during the configure step that you provide your Qt package.
-
-From the root of the repository, execute `cmake` specifying the path to an arbitrary build folder and the path to your QT5 package.
-
-For example:
-
-```bash
-cmake -B cmake-build -DRV_DEPS_QT5_LOCATION=/Path/To/Your/Qt5/Rootr
-```
-
-### Custom generator
-
-You can decide to build with another generator. Ninja is known to work well with the build. If you desire to build with Ninja, you can set`-G Ninja`
-
-## Build (including incremental builds)
-
-Invoke the build tool using cmake (recommended).
-
-For example:
-
-```bash
-cmake --build cmake-build --target rv
-```
+WARNING: If you fetch Qt from another source, make sure to build it with SSL support, that it contains everything required to build PySide2, and that the file structure is similar to the official package.

doc/build_system/config_macos.md renamed to docs/build_system/config_macos.md

@@ -7,8 +7,6 @@
 1. [Install tools and build dependencies](#install-tools-and-build-dependencies)
 1. [Install the python requirements](#install-the-python-requirements)
 1. [Install Qt](#install-qt)
-1. [Configure CMake](#configure)
-1. [Invoke CMake](#build-including-incremental-builds)
 
 ## Install XCode
 
@@ -46,31 +44,6 @@ python3 -m pip install -r requirements.txt
 Download the last version of Qt 5.15.x that you can get using the online installer on the [Qt page](https://www.qt.io/download-open-source). Logs, Android, iOS and WebAssembly are not required to build OpenRV.
 
 
-WARNING: If you decide fetch Qt from another source, make sure to build it with SSL support and that  it contains everything required to build PySide2 and that the file structure is similar to the official package.
-FYI. Qt5 from homebrew is known to not work well with OpenRV.
+WARNING: If you fetch Qt from another source, make sure to build it with SSL support, that it contains everything required to build PySide2, and that the file structure is similar to the official package.
 
-## Configure
-
-The project uses CMake and requires a configure step before building. It is during the configure step that you provide your Qt package.
-
-From the root of the repository, execute `cmake` specifying the path to an arbitrary build folder and the path to your QT5 package.
-
-For example:
-
-```bash
-cmake -B cmake-build -DCMAKE_BUILD_TYPE=Release -DRV_DEPS_QT5_LOCATION=$HOME/Qt/5.15.2/clang_64
-```
-
-### Custom generator
-
-You can decide to build with another generator. Ninja is known to work well with the build. If you desire to build with Ninja, you can set`-G Ninja`
-
-## Build (including incremental builds)
-
-Invoke the build tool using cmake (recommended).
-
-For example
-
-```bash
-cmake --build cmake-build --target RV
-```
+Note: Qt5 from homebrew is known to not work well with OpenRV.