doc: link-roles: clean up setup() method

The setup() method is trying to find the zephyr repository by name,
but it's not passing allow_paths=False to the west method it uses to
search.

That may lead to unpredictable results depending on what the current
working directory is in the calling environment.

For robustness, disallow paths and make sure we are only searching for
the zephyr project by name.

Add some more comments to explain what is going on and clean up the
empty string handling while we're here.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

doc/_extensions/zephyr/link-roles.py

@@ -31,15 +31,27 @@ def get_github_rev():
 def setup(app):
     rev = get_github_rev()
 
-    # try to get url from West; this adds compatibility with repos
-    # located elsewhere
+    # Try to get the zephyr repository's GitHub URL from the manifest.
+    #
+    # This allows building the docs in downstream Zephyr-based
+    # software with forks of the zephyr repository, and getting
+    # :zephyr_file: / :zephyr_raw: output that links to the fork,
+    # instead of mainline zephyr.
+    baseurl = None
     if west_manifest is not None:
-        baseurl = west_manifest.get_projects(['zephyr'])[0].url
-    else:
-        baseurl = None
+        try:
+            # This search tries to look up a project named 'zephyr'.
+            # If zephyr is the manifest repository, this raises
+            # ValueError, since there isn't any such project.
+            baseurl = west_manifest.get_projects(['zephyr'],
+                                                 allow_paths=False)[0].url
+            # Spot check that we have a non-empty URL.
+            assert baseurl
+        except ValueError:
+            pass
 
-    # or fallback to default
-    if baseurl is None or baseurl == '':
+    # If the search failed, fall back on the mainline URL.
+    if baseurl is None:
         baseurl = 'https://github.com/zephyrproject-rtos/zephyr'
 
     app.add_role('zephyr_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))