Update docs for overriding rapids-cmake

rapidsai#257 updated the readme,
but forgot to update `basics.rst`. Copy the text from the readme.

docs/basics.rst

@@ -48,24 +48,41 @@ There are two ways projects can use ``rapids-cmake`` functions.
 Overriding RAPIDS.cmake
 ***********************
 
-At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you need to override the default git repository and branch that ``RAPIDS.cmake`` downloads, which should be done
-like this:
-
-.. code-block:: cmake
+At times projects or developers will need to verify ``rapids-cmake`` branches. To do this you can set variables that control which repository ``RAPIDS.cmake`` downloads, which should be done like this:
 
+```cmake
+ # To override the version that is pulled:
+ set(rapids-cmake-version "<version>")
  include(FetchContent)
  FetchContent_Declare(
  rapids-cmake
  GIT_REPOSITORY https:/<my_fork>/rapids-cmake.git
  GIT_TAG <my_feature_branch>
  )
- file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-24.10/RAPIDS.cmake
+ file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-21.12/RAPIDS.cmake
+ # To override the GitHub repository:
+ set(rapids-cmake-repo "<my_fork>")
+ # To use an exact Git SHA:
+ set(rapids-cmake-sha "<my_git_sha>")
+ # To use a Git tag:
+ set(rapids-cmake-tag "<my_git_tag>")
+ # To override the repository branch:
+ set(rapids-cmake-branch "<my_feature_branch>")
+ # Or to override the entire repository URL (e.g. to use a GitLab repo):
+ set(rapids-cmake-url "https://gitlab.com/<my_user>/<my_fork>/-/archive/<my_branch>/<my_fork>-<my_branch>.zip")
+ file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/branch-22.10/RAPIDS.cmake
  ${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
  include(${CMAKE_CURRENT_BINARY_DIR}/RAPIDS.cmake)
-
+```
 
 This tells ``FetchContent`` to ignore the explicit url and branch in ``RAPIDS.cmake`` and use the
 ones provided.
+A few notes:
+
+- An explicitly defined ``rapids-cmake-url`` will always be used
+- `rapids-cmake-sha` takes precedence over `rapids-cmake-tag`
+- `rapids-cmake-tag` takes precedence over `rapids-cmake-branch`
+- It is advised to always set `rapids-cmake-version` to the version expected by the repo your modifications will pull
 
 An incorrect approach that people try is to modify the ``file(DOWNLOAD)`` line to point to the
 custom ``rapids-cmake`` branch. That doesn't work as the downloaded ``RAPIDS.cmake`` contains