Generate relative links for same-package documentation

GearsDatapacks · GearsDatapacks · commit 789205ec4908 · 2025-05-04T11:11:38.000+01:00
diff --git a/compiler-core/src/docs/printer.rs b/compiler-core/src/docs/printer.rs
@@ -460,6 +460,58 @@ impl Printer<'_> {
             self.title(name)
         } else if package == self.package && module == self.module {
             self.link(eco_format!("#{name}"), self.title(name), None)
+        } else if package == self.package {
+            // If we are linking to the current package, we might be viewing the
+            // documentation locally and so we need to generate a relative link.
+
+            let mut module_path = module.split('/').peekable();
+            let mut current_module = self.module.split('/');
+
+            // The documentation page for the final segment of the module is just
+            // an html file by itself, so it doesn't form part of the path and doesn't
+            // need to be backtracked using `..`.
+            let module_name = module_path.next_back().unwrap_or(module);
+            _ = current_module.next_back();
+
+            // The two modules might have some sharer part of the path, which we
+            // don't need to traverse back through. However, if the two modules are
+            // something like `gleam/a/wibble/wobble` and `gleam/b/wibble/wobble`,
+            // the `wibble` folders are two different folders despite being at the
+            // same position with the same name.
+            let mut encountered_different_path = false;
+            let mut path = Vec::new();
+
+            // Calculate how far backwards in the directory tree we need to walk
+            for segment in current_module {
+                // If this is still part of the shared path, we can just skip it:
+                // no need to go back and forth through the same directory in the
+                // path!
+                if !encountered_different_path && module_path.peek() == Some(&segment) {
+                    _ = module_path.next();
+                } else {
+                    encountered_different_path = true;
+                    path.push("..");
+                }
+            }
+
+            // Once we have walked backwards, we walk forwards again to the correct
+            // page.
+            path.extend(module_path);
+            path.push(module_name);
+
+            let qualified_name = docvec![
+                self.variable(EcoString::from(module_name)),
+                ".",
+                self.title(name)
+            ];
+
+            let title = eco_format!("{module}.{{type {name}}}");
+
+            self.link(
+                eco_format!("{path}.html#{name}", path = path.join("/")),
+                qualified_name,
+                Some(title),
+            )
         } else {
             let module_name = module.split('/').next_back().unwrap_or(module);
             let qualified_name = docvec![
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module.snap
@@ -16,4 +16,4 @@ pub fn make_dict() -> dict.Dict(a, b) { todo }
 ---- VALUES
 
 --- make_dict
-<pre><code>pub fn make_dict() -> <a href="https://hexdocs.pm/thepackage/gleam/dict.html#Dict" title="gleam/dict.{type Dict}">dict.Dict</a>(a, b)</code></pre>
+<pre><code>pub fn make_dict() -> <a href="gleam/dict.html#Dict" title="gleam/dict.{type Dict}">dict.Dict</a>(a, b)</code></pre>
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module_from_nested_module.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module_from_nested_module.snap
@@ -0,0 +1,19 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- gleam/dict.gleam
+pub type Dict(a, b)
+
+-- gleam/dynamic/decode.gleam
+
+import gleam/dict
+
+pub fn decode_dict() -> dict.Dict(a, b) { todo }
+
+
+---- VALUES
+
+--- decode_dict
+<pre><code>pub fn decode_dict() -> <a href="../dict.html#Dict" title="gleam/dict.{type Dict}">dict.Dict</a>(a, b)</code></pre>
diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module_from_nested_module_with_shared_path.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__link_to_type_in_different_module_from_nested_module_with_shared_path.snap
@@ -0,0 +1,20 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- gleam/dynamic.gleam
+pub type Dynamic
+
+-- gleam/dynamic/decode.gleam
+
+import gleam/dynamic
+
+pub type Dynamic = dynamic.Dynamic
+
+
+---- TYPES
+
+--- Dynamic
+<pre><code>pub type Dynamic =
+  <a href="../dynamic.html#Dynamic" title="gleam/dynamic.{type Dynamic}">dynamic.Dynamic</a></code></pre>
diff --git a/compiler-core/src/docs/tests.rs b/compiler-core/src/docs/tests.rs
@@ -133,19 +133,20 @@ pub fn compile(config: PackageConfig, modules: Vec<(&str, &str)>) -> EcoString {
 }
 
 fn compile_documentation(
-    main_module: &str,
+    module_name: &str,
+    module_src: &str,
     modules: Vec<(&str, &str, &str)>,
     options: PrintOptions,
 ) -> EcoString {
-    let module = type_::tests::compile_module("main", main_module, None, modules.clone())
+    let module = type_::tests::compile_module(module_name, module_src, None, modules.clone())
         .expect("Module should compile successfully");
 
     let mut config = PackageConfig::default();
     config.name = "thepackage".into();
     let paths = ProjectPaths::new("/".into());
     let build_module = build::Module {
         name: "main".into(),
-        code: main_module.into(),
+        code: module_src.into(),
         mtime: SystemTime::now(),
         input_path: "/".into(),
         origin: Origin::Src,
@@ -168,7 +169,14 @@ fn compile_documentation(
     let types = module
         .definitions
         .iter()
-        .filter_map(|statement| printer.type_definition(&source_links, statement))
+        .filter_map(
+            |statement: &crate::ast::Definition<
+                std::sync::Arc<type_::Type>,
+                crate::ast::TypedExpr,
+                EcoString,
+                EcoString,
+            >| printer.type_definition(&source_links, statement),
+        )
         .sorted()
         .collect_vec();
 
@@ -185,8 +193,10 @@ fn compile_documentation(
     for (_package, name, src) in modules {
         output.push_str(&format!("-- {name}.gleam\n{src}\n\n"));
     }
-    output.push_str("-- main.gleam\n");
-    output.push_str(main_module);
+    output.push_str("-- ");
+    output.push_str(module_name);
+    output.push_str(".gleam\n");
+    output.push_str(module_src);
 
     if !types.is_empty() {
         output.push_str("\n\n---- TYPES");
@@ -241,27 +251,32 @@ macro_rules! assert_documentation {
     };
 
     ($src:literal, $options:expr $(,)?) => {
-        let output = compile_documentation($src, Vec::new(), $options);
+        let output = compile_documentation("main", $src, Vec::new(), $options);
         insta::assert_snapshot!(output);
     };
 
     ($(($name:expr, $module_src:literal)),+, $src:literal $(,)?) => {
-        let output = compile_documentation($src, vec![$(("thepackage", $name, $module_src)),*], PrintOptions::all());
+        let output = compile_documentation("main", $src, vec![$(("thepackage", $name, $module_src)),*], PrintOptions::all());
         insta::assert_snapshot!(output);
     };
 
     ($(($name:expr, $module_src:literal)),+, $src:literal, $options:expr $(,)?) => {
-        let output = compile_documentation($src, vec![$(("thepackage", $name, $module_src)),*], $options);
+        let output = compile_documentation("main", $src, vec![$(("thepackage", $name, $module_src)),*], $options);
+        insta::assert_snapshot!(output);
+    };
+
+    ($(($name:expr, $module_src:literal)),+, $main_module:literal, $src:literal, $options:expr $(,)?) => {
+        let output = compile_documentation($main_module, $src, vec![$(("thepackage", $name, $module_src)),*], $options);
         insta::assert_snapshot!(output);
     };
 
     ($(($package:expr, $name:expr, $module_src:literal)),+, $src:literal $(,)?) => {
-        let output = compile_documentation($src, vec![$(($package, $name, $module_src)),*], PrintOptions::all());
+        let output = compile_documentation("main", $src, vec![$(($package, $name, $module_src)),*], PrintOptions::all());
         insta::assert_snapshot!(output);
     };
 
     ($(($package:expr, $name:expr, $module_src:literal)),+, $src:literal, $options:expr $(,)?) => {
-        let output = compile_documentation($src, vec![$(($package, $name, $module_src)),*], $options);
+        let output = compile_documentation("main", $src, vec![$(($package, $name, $module_src)),*], $options);
         insta::assert_snapshot!(output);
     };
 }
@@ -834,6 +849,34 @@ pub fn make_dict() -> dict.Dict(a, b) { todo }
     );
 }
 
+#[test]
+fn link_to_type_in_different_module_from_nested_module() {
+    assert_documentation!(
+        ("gleam/dict", "pub type Dict(a, b)"),
+        "gleam/dynamic/decode",
+        "
+import gleam/dict
+
+pub fn decode_dict() -> dict.Dict(a, b) { todo }
+",
+        ONLY_LINKS
+    );
+}
+
+#[test]
+fn link_to_type_in_different_module_from_nested_module_with_shared_path() {
+    assert_documentation!(
+        ("gleam/dynamic", "pub type Dynamic"),
+        "gleam/dynamic/decode",
+        "
+import gleam/dynamic
+
+pub type Dynamic = dynamic.Dynamic
+",
+        ONLY_LINKS
+    );
+}
+
 // https://github.com/gleam-lang/gleam/issues/3461
 #[test]
 fn link_to_type_in_different_package() {
