used rel path for local url (#27)

* used rel path for local url

* used rel path for doc link

* updated docs

* updated docs

* updated doc string

* removed commented code

* fixed typo

Author: juiwenchen

docs/source/components/directive.rst

@@ -75,6 +75,4 @@ The needs defined in source code are extracted and rendered to:
    :project: dcdc
    :directory: ./discharge
 
-.. note:: **local-url** is not working on the website as it only supports local browsing.
-
 To have a more customized configuration of ``CodeLinks``, please refer to :ref:`configuration <configuration>`.

docs/source/development/change_log.rst

@@ -3,6 +3,16 @@
 Changelog
 =========
 
+.. _`unreleased`:
+
+Unreleased
+----------
+
+Fixes
+.....
+
+- 🐛 Replace absolute path with relative path to fix ``local-url`` not working on the non-local environment
+
 .. _`release:1.0.0`:
 
 1.0.0
@@ -26,7 +36,7 @@ New and Improved
 
 - ✨ Added a new ``write rst`` CLI command.
 
-  The ``write rst`` command write a reStructuredText file with :external+needs:ref:`needextend <needextend>` directive from the extracted markers generated by ``analyse``.
+  The ``write rst`` command writes a reStructuredText file with :external+needs:ref:`needextend <needextend>` directive from the extracted markers generated by ``analyse``.
   The generated RST can be included in the Sphinx documentation to create the source code links in the existing needs
 
 - 🔨 Replaced ``virtual_docs`` with the new ``analyse`` module.
@@ -53,7 +63,7 @@ New and Improved
 Fixes
 .....
 
-- 🐛 Applying default configuration value when not given
+- 🐛 Apply default configuration values when not given
 
   When a user does not specify certain configuration options, the extension will automatically use predefined default
   values, allowing users to get started quickly without needing to customize every option.

src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -33,6 +33,15 @@
 logger = logging.getLogger(__name__)
 
 
+def get_rel_path(doc_path: Path, code_path: Path, base_dir: Path) -> tuple[Path, Path]:
+    """Get the relative path from the document to the source code file and vice versa."""
+    doc_depth = len(doc_path.parents) - 1
+    src_rel_path = Path(*[".."] * doc_depth) / code_path.relative_to(base_dir)
+    code_depth = len(code_path.relative_to(base_dir).parents) - 1
+    doc_rel_path = Path(*[".."] * code_depth) / doc_path
+    return src_rel_path, doc_rel_path.with_suffix(".html")
+
+
 def generate_str_link_name(
     oneline_need: OneLineNeed,
     target_filepath: Path,
@@ -145,7 +154,7 @@ def run(self) -> list[nodes.Node]:
                 to_remove_str = to_remove_str.replace("\\", "\\\\")
             self.env.config.needs_string_links[local_url_field] = {
                 "regex": r"^(?P<value>.+?)\.[^\.]+#L(?P<lineno>\d+)",
-                "link_url": ("file://{{value}}.html#L-{{lineno}}"),
+                "link_url": ("{{value}}.html#L-{{lineno}}"),
                 "link_name": f"{{{{value | replace('{to_remove_str}', '')}}}}#L{{{{lineno}}}}",
                 "options": [local_url_field],
             }
@@ -259,7 +268,7 @@ def render_needs(
             # mapping between lineno and need link in docs for local url
 
             # The link to the documentation page for the source file
-            docs_href = f"{dirs['out_dir'] / self.env.docname}.html"
+
             if local_url_field:
                 # copy files to _build/html
                 target_filepath.parent.mkdir(parents=True, exist_ok=True)
@@ -268,8 +277,15 @@ def render_needs(
             remote_link_name = None
             if local_url_field:
                 # generate link name
+                # calculate the relative path from the current doc to the target file
+                local_rel_path, docs_href = get_rel_path(
+                    Path(self.env.docname), target_filepath, dirs["out_dir"]
+                )
                 local_link_name = generate_str_link_name(
-                    oneline_need, target_filepath, dirs, local=True
+                    oneline_need,
+                    local_rel_path,
+                    dirs,
+                    local=True,
                 )
             if remote_url_field:
                 remote_link_name = generate_str_link_name(