From a621af5925449d1694bee0a0a3573d05e903480d Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Thu, 21 Nov 2024 11:37:31 -0500 Subject: [PATCH 01/10] Add canonical link --- compiler-core/src/docs/tests.rs | 16 ++++++++++++++++ .../templates/documentation_layout.html | 1 + .../templates/documentation_module.html | 6 ++++++ 3 files changed, 23 insertions(+) diff --git a/compiler-core/src/docs/tests.rs b/compiler-core/src/docs/tests.rs index 1f18e0d2c49..d5e5d761877 100644 --- a/compiler-core/src/docs/tests.rs +++ b/compiler-core/src/docs/tests.rs @@ -366,3 +366,19 @@ fn source_link_for_github_repository_with_path() { "https://github.com/wibble/wobble/blob/v0.1.0/path/to/package/src/app.gleam#L1-L1" )); } + +#[test] +fn canonical_link() { + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_canonical"); + let modules = vec![( + "app.gleam", + r#" +/// Here is some documentation +pub fn one() { + 1 +} +"#, + )]; + insta::assert_snapshot!(compile(config, modules)); +} diff --git a/compiler-core/templates/documentation_layout.html b/compiler-core/templates/documentation_layout.html index e7119dca0ee..cfd20d1c4e0 100644 --- a/compiler-core/templates/documentation_layout.html +++ b/compiler-core/templates/documentation_layout.html @@ -12,6 +12,7 @@ between multiple versions of the same package. --> + {% block head %}{%- endblock %} + + +"test_canconical" +"app" + + + + + + +
+ + +

+ test_canconical + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

+ app + +

+ + + + + + + +
+

+ Functions + +

+ +
+
+

+ + one + +

+ +
+ + 
pub fn one() -> Int
+ +

Here is some documentation

+
+
+ +
+ + +
+
+
+ + + ✨ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap index 955f604c38f..086bec843c2 100644 --- a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap +++ b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap @@ -18,6 +18,7 @@ expression: "compile(config, modules)" between multiple versions of the same package. --> + + + + + + + + + + + + + + + + + +
+ + +

+ test_canonical + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

LICENSE

+ + +
+
+
+ + + ✨ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + + +//// app.html + + + + + + + app · test_canonical · v0.1.0 + + + + + + + + + + + + + + +
+ + +

+ test_canonical + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

+ app + +

+ + + + + + + +
+

+ Functions + +

+ +
+
+

+ + one + +

+ +
+ + 
pub fn one() -> Int
+ +

Here is some documentation

+
+
+ +
+ + +
+
+
+ + + ✨ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + + +//// gleam/otp/actor.html + + + + + + + gleam/otp/actor · test_canonical · v0.1.0 + + + + + + + + + + + + + + +
+ + +

+ test_canonical + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

+ gleam/otp/actor + +

+ + + + + + + +
+

+ Functions + +

+ +
+
+

+ + one + +

+ +
+ + 
pub fn one() -> Int
+ +

Here is some documentation

+
+
+ +
+ + +
+
+
+ + + ✨ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + From 138600d88d76be70d8c2fbd2554d0493cc6b28bb Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Wed, 4 Dec 2024 16:44:46 -0500 Subject: [PATCH 05/10] Remove typo snapshot --- ...am_core__docs__tests__canconical_link.snap | 361 ------------------ 1 file changed, 361 deletions(-) delete mode 100644 compiler-core/src/docs/snapshots/gleam_core__docs__tests__canconical_link.snap diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canconical_link.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canconical_link.snap deleted file mode 100644 index 4709a86613a..00000000000 --- a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canconical_link.snap +++ /dev/null @@ -1,361 +0,0 @@ ---- -source: compiler-core/src/docs/tests.rs -expression: "compile(config, modules)" ---- -//// app.html - - - - - - - app · test_canconical · v0.1.0 - - - - - - - - -"test_canconical" -"app" - - - - - - -
- - -

- test_canconical - - - v0.1.0 - - -

-
-
- - -
-
-
- - - -
- -
- - -
- -

- app - -

- - - - - - - -
-

- Functions - -

- -
-
-

- - one - -

- -
- - 
pub fn one() -> Int
- -

Here is some documentation

-
-
- -
- - -
-
-
- - - ✨ -
-
Lucy
-
says
-
trans
-
rights
-
now
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - Search - - - - - - - Document - - - - - - - - - - - - - - - - - - - - - From a659dfbb13ac3cb21948252160e14b03ebd89dec Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Wed, 4 Dec 2024 17:45:32 -0500 Subject: [PATCH 06/10] Remove duplicate host --- compiler-core/src/docs.rs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/compiler-core/src/docs.rs b/compiler-core/src/docs.rs index 32aba1c59bd..ea0e77e4c9d 100644 --- a/compiler-core/src/docs.rs +++ b/compiler-core/src/docs.rs @@ -125,11 +125,6 @@ pub fn generate_html( "index" => config.description.to_string().clone(), _other => "".to_owned(), }; - let host = if is_hex_publish == DocContext::HexPublish { - "https://hexdocs.pm" - } else { - "" - }; let path = Utf8PathBuf::from(&page.path); let temp = PageTemplate { From 0be51b8c98b59bdbf222e671a18a76d11936d3fe Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Mon, 9 Dec 2024 17:08:14 -0500 Subject: [PATCH 07/10] Add no hex publish test. Add project name to docs tests --- ...eam_core__docs__tests__canonical_link.snap | 32 +- ...re_not_used_by_the_following_function.snap | 10 +- ...n_code_from_module_comment_is_trimmed.snap | 10 +- ..._from_standalone_pages_is_not_trimmed.snap | 12 +- ...eam_core__docs__tests__no_hex_publish.snap | 1031 +++++++++++++++++ compiler-core/src/docs/tests.rs | 92 +- 6 files changed, 1145 insertions(+), 42 deletions(-) create mode 100644 compiler-core/src/docs/snapshots/gleam_core__docs__tests__no_hex_publish.snap diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap index 41b64fca7bc..7bb68cb1431 100644 --- a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap +++ b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap @@ -1,6 +1,6 @@ --- source: compiler-core/src/docs/tests.rs -expression: "compile_with_markdown_pages(config, modules, pages)" +expression: "compile_with_markdown_pages(config, modules, pages,\nCompileWithMarkdownPagesOpts::default())" --- //// LICENSE.html @@ -9,7 +9,7 @@ expression: "compile_with_markdown_pages(config, modules, pages)" - LICENSE · test_canonical · v0.1.0 + LICENSE · test_project_name · v0.1.0 @@ -18,7 +18,7 @@ expression: "compile_with_markdown_pages(config, modules, pages)" between multiple versions of the same package. --> - + - + - + - + - + - + + + + + + + + + +
+ + +

+ test_project_name + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

LICENSE

+ + +
+
+
+ + + ✨ +
+
Lucy
+
says
+
trans
+
rights
+
now
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + + +//// app.html + + + + + + + app · test_project_name · v0.1.0 + + + + + + + + + + + + + + +
+ + +

+ test_project_name + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

+ app + +

+ + + + + + + +
+

+ Functions + +

+ +
+
+

+ + one + +

+ +
+ + 
pub fn one() -> Int
+ +

Here is some documentation

+
+
+ +
+ + +
+
+
+ + + ✨ +
+
Lucy
+
says
+
trans
+
rights
+
now
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + + +//// gleam/otp/actor.html + + + + + + + gleam/otp/actor · test_project_name · v0.1.0 + + + + + + + + + + + + + + +
+ + +

+ test_project_name + + - v0.1.0 + + +

+
+
+ + +
+
+
+ + + +
+ +
+ + +
+ +

+ gleam/otp/actor + +

+ + + + + + + +
+

+ Functions + +

+ +
+
+

+ + one + +

+ +
+ + 
pub fn one() -> Int
+ +

Here is some documentation

+
+
+ +
+ + +
+
+
+ + + ✨ +
+
Lucy
+
says
+
trans
+
rights
+
now
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + Search + + + + + + + Document + + + + + + + + + + + + + + + + + + + + + diff --git a/compiler-core/src/docs/tests.rs b/compiler-core/src/docs/tests.rs index 23ef3dfda83..a0104e02443 100644 --- a/compiler-core/src/docs/tests.rs +++ b/compiler-core/src/docs/tests.rs @@ -14,10 +14,16 @@ use camino::Utf8PathBuf; use ecow::EcoString; use itertools::Itertools; +#[derive(Default)] +struct CompileWithMarkdownPagesOpts { + hex_publish: Option, +} + fn compile_with_markdown_pages( config: PackageConfig, modules: Vec<(&str, &str)>, markdown_pages: Vec<(&str, &str)>, + opts: CompileWithMarkdownPagesOpts, ) -> EcoString { let fs = InMemoryFileSystem::new(); for (name, src) in modules { @@ -83,7 +89,11 @@ fn compile_with_markdown_pages( &docs_pages, pages_fs, SystemTime::UNIX_EPOCH, - DocContext::HexPublish, + if let Some(doc_context) = opts.hex_publish { + doc_context + } else { + DocContext::HexPublish + }, ) .into_iter() .filter(|file| file.path.extension() == Some("html")) @@ -103,7 +113,12 @@ fn compile_with_markdown_pages( } pub fn compile(config: PackageConfig, modules: Vec<(&str, &str)>) -> EcoString { - compile_with_markdown_pages(config, modules, vec![]) + compile_with_markdown_pages( + config, + modules, + vec![], + CompileWithMarkdownPagesOpts::default(), + ) } #[test] @@ -201,7 +216,8 @@ fn discarded_arguments_are_not_shown() { // https://github.com/gleam-lang/gleam/issues/2631 #[test] fn docs_of_a_type_constructor_are_not_used_by_the_following_function() { - let config = PackageConfig::default(); + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); let modules = vec![( "app.gleam", r#" @@ -220,7 +236,8 @@ pub fn main() { todo } #[test] fn markdown_code_from_standalone_pages_is_not_trimmed() { - let config = PackageConfig::default(); + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); let pages = vec![( "one", " @@ -231,7 +248,12 @@ pub fn indentation_test() { } ```", )]; - insta::assert_snapshot!(compile_with_markdown_pages(config, vec![], pages)); + insta::assert_snapshot!(compile_with_markdown_pages( + config, + vec![], + pages, + CompileWithMarkdownPagesOpts::default() + )); } #[test] @@ -256,7 +278,8 @@ pub fn indentation_test() { #[test] fn markdown_code_from_module_comment_is_trimmed() { - let config = PackageConfig::default(); + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); let modules = vec![( "app.gleam", " @@ -289,7 +312,8 @@ pub const wobble = 1 #[test] fn doc_for_commented_definitions_is_not_included_in_next_type() { - let config = PackageConfig::default(); + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); let modules = vec![( "app.gleam", " @@ -324,7 +348,8 @@ pub fn wobble(arg) {} #[test] fn doc_for_commented_definitions_is_not_included_in_next_type_alias() { - let config = PackageConfig::default(); + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); let modules = vec![( "app.gleam", " @@ -355,6 +380,7 @@ fn source_link_for_github_repository() { #[test] fn source_link_for_github_repository_with_path() { let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); config.repository = Repository::GitHub { user: "wibble".to_string(), repo: "wobble".to_string(), @@ -370,7 +396,7 @@ fn source_link_for_github_repository_with_path() { #[test] fn canonical_link() { let mut config = PackageConfig::default(); - config.name = EcoString::from("test_canonical"); + config.name = EcoString::from("test_project_name"); let modules = vec![ ( "app.gleam", @@ -398,5 +424,51 @@ pub fn one() { # LICENSE "#, )]; - insta::assert_snapshot!(compile_with_markdown_pages(config, modules, pages)); + insta::assert_snapshot!(compile_with_markdown_pages( + config, + modules, + pages, + CompileWithMarkdownPagesOpts::default() + )); +} + +#[test] +fn no_hex_publish() { + let mut config = PackageConfig::default(); + config.name = EcoString::from("test_project_name"); + let modules = vec![ + ( + "app.gleam", + r#" +/// Here is some documentation +pub fn one() { + 1 +} +"#, + ), + ( + "gleam/otp/actor.gleam", + r#" +/// Here is some documentation +pub fn one() { + 1 +} +"#, + ), + ]; + + let pages = vec![( + "LICENSE", + r#" +# LICENSE + "#, + )]; + insta::assert_snapshot!(compile_with_markdown_pages( + config, + modules, + pages, + CompileWithMarkdownPagesOpts { + hex_publish: Some(DocContext::Build) + } + )); } From fdddb0ba362e82fe11abda1374c40deba033d140 Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Mon, 9 Dec 2024 17:13:26 -0500 Subject: [PATCH 08/10] Update CHANGELOG --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e9677a04701..23847bf5c06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -175,6 +175,13 @@ - The formatter now adds a `todo` inside empty blocks. ([Giacomo Cavalieri](https://github.com/giacomocavalieri)) +### Documentation + +- Canonical links created for documentation pages if published on Hex. Previously + published documentation would need to be updated. Resolves versioned pages to point + to latest page for search engines. + ([Dave Lage](https://github.com/rockerBOO)) + ### Bug fixed - The compiler now throws an error when a float literal ends with an `e` and From 6dd9917d2975133c4a8129848657b374d140dd08 Mon Sep 17 00:00:00 2001 From: rockerBOO Date: Mon, 9 Dec 2024 17:15:51 -0500 Subject: [PATCH 09/10] Move docs head block to docs layout --- compiler-core/templates/documentation_layout.html | 2 +- compiler-core/templates/documentation_module.html | 6 ------ compiler-core/templates/documentation_page.html | 6 ------ 3 files changed, 1 insertion(+), 13 deletions(-) diff --git a/compiler-core/templates/documentation_layout.html b/compiler-core/templates/documentation_layout.html index cfd20d1c4e0..b79413a7903 100644 --- a/compiler-core/templates/documentation_layout.html +++ b/compiler-core/templates/documentation_layout.html @@ -12,7 +12,7 @@ between multiple versions of the same package. --> - {% block head %}{%- endblock %} + {% if !host.is_empty() && !project_name.is_empty() -%}{%- endif %} - + - + - + - + - + - +