Merge topic 'docs-add-favicon'

59d69fac docs: replace relative with absolute URLs in Open{VR,XR} modules README
4e4a3625 docs: bring back develop_quickstart
28278edc docs: Add favicon on readthedocs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Acked-by: Jean-Christophe Fillion-Robin <jchris.fillionr@kitware.com>
Merge-request: !10428

Documentation/docs/conf.py

@@ -73,6 +73,7 @@ todo_include_todos = True
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_logo = "../../vtkLogo.ico"
+html_favicon = "../../Utilities/Doxygen/vtk_favicon.png"
 html_theme = "furo"
 
 copybutton_prompt_text = r"\$ | C\:\> |>>> "  # strip promt text on copy

Documentation/docs/developers_guide/.gitignore

-# This is generated by conf.py
-develop_quickstart.md

Documentation/docs/developers_guide/develop_quickstart.md

+# Quick Start Guide
+
+This is a quick start guide so that you can start contributing to VTK easily.
+To understand the process more deeply, you can jump to the [workflow](./git/develop.md#workflow)
+section.
+
+## Initial Setup
+
+Before you begin, perform your initial setup using the following steps:
+
+1.  Register [GitLab Access] to create an account and select a user name.
+
+2.  [Fork VTK][] into your user's namespace on GitLab.
+
+3.  Follow the [download instructions](./git/download.md#clone) to create a
+    local clone of the main VTK repository:
+
+        $ git clone --recursive https://gitlab.kitware.com/vtk/vtk.git VTK
+
+    The main repository will be configured as your `origin` remote.
+
+4.  Run the [developer setup script][] to prepare your VTK work tree and
+    create Git command aliases used below:
+
+        $ ./Utilities/SetupForDevelopment.sh
+
+    This will prompt you for your GitLab username and configure a remote
+    called `gitlab` to refer to your fork. It will also setup a data directory for you.
+    No need to do anything else.
+
+[GitLab Access]: https://gitlab.kitware.com/users/sign_in
+[Fork VTK]: https://gitlab.kitware.com/vtk/vtk/-/forks/new
+[developer setup script]: https://gitlab.kitware.com/vtk/vtk/Utilities/SetupForDevelopment.sh
+
+## Development
+
+Create a local branch for your changes:
+
+```
+git checkout -b your_branch
+```
+
+Make the needed changes in VTK and use git locally to create logically separated commits.
+There is no strict requirements regarding git commit messages syntax but a good rule of
+thumb to follow is: `General domain: reason for change`, General domain being a class, a module
+, a specific system like build or CI.
+
+```
+git commit -m "General domain: Short yet informative reason for the change"
+```
+
+Build VTK following the [guide][] and fix any build warnings or issues that arise and seems related to your changes.
+
+[guide]: ../build_instructions/build.md
+Add/Improve tests in order to ensure your changes are tested. Take a look in the `Testing` directory
+of the module you are making changes in to see how the tests are currently built and try to follow the same paradigms.
+Run your test locally from your build directory and check that they pass:
+
+```
+cmake . && cmake --build .
+ctest -VV -R yourTest
+```
+
+## Upload
+
+Push your changes to the GitLab fork that you created in the [initial setup](#initial-setup) stage:
+
+```
+git push gitlab
+```
+
+## Data
+
+If your test uses new data or baselines, you will need to add it to your fork.
+For data, add the file names to the list in your module `yourModule/Testing/CMakeLists.txt` and drop the files in `Testing/Data/`.
+For baselines, just drop the file in `yourModule/Testing/Data/Baselines` and run the following commands from your build directory:
+
+```
+cmake . && cmake --build .
+```
+
+This will transform your files into .sha512 files. Check your test is passing by running from your build directory:
+
+```
+ctest -VV -R yourTest
+```
+
+If it passes, add these .sha512 files and commit them, then push with:
+
+```
+git gitlab-push
+```
+
+## Create a Merge Request
+
+Once you are happy with the state of your development on your fork, the next step is to create a merge request back into the main VTK repository.
+
+Open [](https://gitlab.kitware.com/username/vtk/-/merge_requests/new) in a browser, select your branch in the list and create a Merge Request against master.
+
+In the description, write an informative explanation of your added features or bugfix. If there is an associated issue, link it with the `#number` in the description.
+
+Tag some VTK maintainers in the description to ensure someone will see it, see here for the complete [list](./git/develop.md#review-a-merge-request).
+
+## Robot Checks
+
+Once the MR is created, our GitLab robot will check multiple things and make automated suggestions. Please read them and try to follow the instructions.
+The two standard suggestions are related to formatting errors and adding markdown changelog.
+
+To fix the formatting, just add a comment containing:
+
+```
+Do: reformat
+```
+
+Then, once the robot has fixed the formatting, fetch the changes locally (this will remove any local changes to your branch)
+
+```
+git fetch gitlab
+git reset --hard gitlab/your_branch
+```
+
+To fix the changelog warning, create, add, commit and push a markdown (.md) file in `Documentation/release/dev` folder.
+In this file, write a small markdown paragraph describing the development.
+See other .md files in this folder for examples. It may look like this:
+
+```
+## Development title
+
+A new feature that does this and that has been introduced.
+This specific issue has been fixed in this particular way.
+```
+
+Suggestions and best practices on writing the changelog can be found in the `Documentation/release/dev/0-sample-topic.md` file.
+This is an optional step but recommended to do for any new feature and user facing issues.
+
+## Reviews
+
+VTK maintainers and developers will review your MR by leaving comments on it. Try to follow their instructions and be patient.
+It can take a while to get a MR into mergeable form. This is a mandatory step, and it is absolutely normal to get change requests.
+
+Review comments can be resolved, please resolve a comment once you've taken it into account and pushed related changes
+or once you've reached an agreement with the commenter that nothing should be changed.
+
+Once a reviewer is happy with your changes, they will add a `+X` comment. You need at least one `+2` or higher to consider
+merging the MR. Two `+1`s do not equal a `+2`. If a reviewer leave a `-1` comment, please discuss with them to understand what is the issue and how it could be fixed.
+
+Once you have pushed new changes, please tag reviewers again so that they can take a look.
+If you do not tag reviewers, they may not know to revisit your changes. _Do not hesitate to tag them and ask for help_.
+
+## Continuous Integration
+
+Before merging a MR, the VTK continuous integration (CI) needs to run and be green.
+For CI to be functional, please read and follow this [guide](https://discourse.vtk.org/t/the-ultimate-how-to-make-ci-work-with-my-fork-guide/7581).
+
+To run the CI:
+ - Click on the Pipelines Tab
+ - Click on the last pipeline status badge
+ - Press the `Play all manual` arrows on top of the Build and Test stages
+
+Do not hesitate to tag a VTK developer for help if needed.
+
+You then need to wait for CI to run, it can take a while, up to a full day.
+
+A successful CI should be fully green. If that is so, then your MR is ready !
+
+If not, you need to analyse the issues and fix them. Recover the failure information this way:
+
+Click on the pipelines tab, then on the last status badge, then on the `cdash-commit` job.
+It will take you to the related CDash report where you will find all information.
+
+Everything in the CDash report should be green except the `NotRun` and `Time` column. Take a look into each issue and fix them locally.
+If there are issues in the pipeline but nothing is visible in the CDash, please ask a maintainer for help to figure out if anything should be done.
+You can always try to rerun the failed job by clicking on the arrow of the job in the pipeline.
+
+Once you have fixed some issues locally, commit and push them to gitlab, run the CI again and tag reviewers again for follow-up reviews.
+
+## Merging
+
+Once the MR has green CI and you have at least one `+2`, you can ask for a merge. Before that please make sure that:
+ - Your commit history is logical (or squashed into a single commit) and cleaned up with good commit messages
+ - You are rebased on a fairly recent version of master
+
+If that is not the case, please rebase on master using the following commands:
+
+```
+git fetch origin
+git rebase -i origin/master
+git push gitlab -f
+```
+
+The interactive rebase will let you squash commits, reorganize commits and edit commit messages.
+
+After the force push, make sure to run CI again.
+
+Once all is done, tag a VTK developer so that they can perform the merge command.
+
+__Congratulations ! You just contributed to VTK !__

Rendering/OpenVR/README.md

@@ -21,10 +21,10 @@ is theoretically supported. Devices include:
 ## Supported Controllers
 
 The VTK `OpenVR` module provides bindings for the following controllers:
-- [HP Motion Controller](vtk_openvr_binding_hpmotioncontroller.json)
-- [Valve Knuckles](vtk_openvr_binding_knuckles.json)
-- [Oculus Touch](vtk_openvr_binding_oculus_touch.json)
-- [HTC Vive Controller](vtk_openvr_binding_vive_controller.json)
+- HP Motion Controller [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenVR/vtk_openvr_binding_hpmotioncontroller.json)
+- Valve Knuckles [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenVR/vtk_openvr_binding_knuckles.json)
+- Oculus Touch [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenVR/vtk_openvr_binding_oculus_touch.json)
+- HTC Vive Controller [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenVR/vtk_openvr_binding_vive_controller.json)
 
 The VTK `OpenVR` module is considered legacy and not under active development.
 Please see the VTK `OpenXR` module for support for additional controllers and
@@ -35,5 +35,5 @@ alternate input mechanisms.
 A minimum [OpenVRCone](https://examples.vtk.org/site/Cxx/GeometricObjects/OpenVRCone/) example is
 available for download on the [VTK Examples website](https://examples.vtk.org/site/).
 
-Tests in the [`Testing/Cxx`](Testing/Cxx) directory may also be run to demonstrate VTK `RenderingOpenVR`
+Tests in the [`Testing/Cxx`](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenVR/Testing/Cxx) directory may also be run to demonstrate VTK `RenderingOpenVR`
 capabilities.

Rendering/OpenXR/README.md

@@ -21,11 +21,11 @@ limited to the following:
 - HP Reverb G2
 
 Supported input devices and mechanisms include the following:
-- [HP Mixed Reality Controller](vtk_openxr_binding_hp_mixed_reality.json)
-- [HTC Vive Controller](vtk_openxr_binding_htc_vive_controller.json)
-- [KHR Simple Controller](vtk_openxr_binding_khr_simple_controller.json)
-- [Valve Knuckles](vtk_openxr_binding_knuckles.json)
-- [Microsoft Hand Interaction](vtk_openxr_binding_microsoft_hand_interaction.json)
+- HP Mixed Reality Controller [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_binding_hp_mixed_reality.json)
+- HTC Vive Controller [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_binding_htc_vive_controller.json)
+- KHR Simple Controller [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_binding_khr_simple_controller.json)
+- Valve Knuckles [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_binding_knuckles.json)
+- Microsoft Hand Interaction [json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_binding_microsoft_hand_interaction.json)
 
 The `OpenXR` module is commonly tested with the Valve Index and HTC Vive
 virtual reality headsets.
@@ -41,7 +41,7 @@ The OpenXR interaction profile specification is documented here:
 https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#semantic-path-interaction-profiles
 
 Input binding JSON files should be added to `OpenXR` and set as default in
-[`vtk_openxr_actions.json`](vtk_openxr_actions.json).
+`vtk_openxr_actions.json`[json](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/vtk_openxr_actions.json).
 
 ## Building
 
@@ -65,7 +65,7 @@ VTK-build > cmake --build . --config "Release"
 
 ## Testing
 
-Minimum OpenXR examples are available in the [`Testing/Cxx`](./Testing/Cxx) directory for testing.
+Minimum OpenXR examples are available in the [`Testing/Cxx`](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Rendering/OpenXR/Testing/Cxx) directory for testing.
 
 To run OpenXR tests, first build VTK with testing enabled.