[backport] Add docs to better distinguish among getProjectPath, getCurrentDir and currentSourcePath (#12565)

Fixes https://github.com/nim-lang/Nim/issues/10477.

lib/core/macros.nim

@@ -1626,9 +1626,29 @@ macro unpackVarargs*(callee: untyped; args: varargs[untyped]): untyped =
     result.add args[i]
 
 proc getProjectPath*(): string = discard
-  ## Returns the path to the currently compiling project, not to
-  ## be confused with ``system.currentSourcePath`` which returns
-  ## the path of the current module.
+  ## Returns the path to the currently compiling project.
+  ##
+  ## This is not to be confused with `system.currentSourcePath <system.html#currentSourcePath.t>`_
+  ## which returns the path of the source file containing that template
+  ## call.
+  ##
+  ## For example, assume a ``dir1/foo.nim`` that imports a ``dir2/bar.nim``,
+  ## have the ``bar.nim`` print out both ``getProjectPath`` and
+  ## ``currentSourcePath`` outputs.
+  ##
+  ## Now when ``foo.nim`` is compiled, the ``getProjectPath`` from
+  ## ``bar.nim`` will return the ``dir1/`` path, while the ``currentSourcePath``
+  ## will return the path to the ``bar.nim`` source file.
+  ##
+  ## Now when ``bar.nim`` is compiled directly, the ``getProjectPath``
+  ## will now return the ``dir2/`` path, and the ``currentSourcePath``
+  ## will still return the same path, the path to the ``bar.nim`` source
+  ## file.
+  ##
+  ## The path returned by this proc is set at compile time.
+  ##
+  ## See also:
+  ## * `getCurrentDir proc <os.html#getCurrentDir>`_
 
 when defined(nimMacrosSizealignof):
   proc getSize*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} =

lib/pure/os.nim

@@ -1236,13 +1236,18 @@ proc fileNewer*(a, b: string): bool {.rtl, extern: "nos$1", noNimScript.} =
     result = getLastModificationTime(a) > getLastModificationTime(b)
 
 proc getCurrentDir*(): string {.rtl, extern: "nos$1", tags: [], noNimScript.} =
-  ## Returns the `current working directory`:idx:.
+  ## Returns the `current working directory`:idx: i.e. where the built
+  ## binary is run.
+  ##
+  ## So the path returned by this proc is determined at run time.
   ##
   ## See also:
   ## * `getHomeDir proc <#getHomeDir>`_
   ## * `getConfigDir proc <#getConfigDir>`_
   ## * `getTempDir proc <#getTempDir>`_
   ## * `setCurrentDir proc <#setCurrentDir,string>`_
+  ## * `currentSourcePath template <system.html#currentSourcePath.t>`_
+  ## * `getProjectPath proc <macros.html#getProjectPath>`_
   when defined(windows):
     var bufsize = MAX_PATH.int32
     when useWinUnicode:

lib/system.nim

@@ -4183,7 +4183,19 @@ when declared(File):
   template `&=`*(f: File, x: typed) = write(f, x)
 
 template currentSourcePath*: string = instantiationInfo(-1, true).filename
-  ## returns the full file-system path of the current source
+  ## Returns the full file-system path of the current source.
+  ##
+  ## To get the directory containing the current source, use it with
+  ## `os.parentDir() <os.html#parentDir%2Cstring>`_ as ``currentSourcePath.parentDir()``.
+  ##
+  ## The path returned by this template is set at compile time.
+  ##
+  ## See the docstring of `macros.getProjectPath() <macros.html#getProjectPath>`_
+  ## for an example to see the distinction between the ``currentSourcePath``
+  ## and ``getProjectPath``.
+  ##
+  ## See also:
+  ## * `getCurrentDir proc <os.html#getCurrentDir>`_
 
 when compileOption("rangechecks"):
   template rangeCheck*(cond) =